diff --git a/.github/workflows/sdk-compliance.yml b/.github/workflows/sdk-compliance.yml index ea14f9b5e..c65042df0 100644 --- a/.github/workflows/sdk-compliance.yml +++ b/.github/workflows/sdk-compliance.yml @@ -2,8 +2,6 @@ name: SDK Compliance Tests permissions: contents: read - packages: read - pull-requests: write on: pull_request: @@ -23,26 +21,81 @@ jobs: with: python-version: "3.12" - name: Install adapter and test dependencies - run: python -m pip install -e . -r sdk_compliance_adapter/requirements.txt pytest pytest-timeout pytest-asyncio + run: python -m pip install -e ".[zstd]" -r sdk_compliance_adapter/requirements.txt pytest pytest-timeout pytest-asyncio - name: Test adapter protocol run: python -m pytest sdk_compliance_adapter/test_adapter.py --timeout=30 compliance: - name: PostHog SDK compliance tests (capture v0) - uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@003d4162421193b458bbaa93fbb7bb0d0104bc3b # 1.31.1 - with: - adapter-dockerfile: "sdk_compliance_adapter/Dockerfile" - adapter-context: "." - test-harness-version: "1.31.1" - continue-on-error: false - report-name: "sdk-compliance-report-v0" - - compliance-v1: - name: PostHog SDK compliance tests (capture v1) - uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@003d4162421193b458bbaa93fbb7bb0d0104bc3b # 1.31.1 - with: - adapter-dockerfile: "sdk_compliance_adapter/Dockerfile.v1" - adapter-context: "." - test-harness-version: "1.31.1" - continue-on-error: false - report-name: "sdk-compliance-report-v1" + # The harness has one enable_compression flag but a test per codec, so each + # job runs the adapter with one codec. The reusable harness workflow cannot + # pass the COMPRESSION env var, so this job runs the containers directly. + # The SDK has no brotli support, so there is no br job. + name: PostHog SDK compliance tests (${{ matrix.compression }}) + runs-on: ubuntu-latest + timeout-minutes: 30 + strategy: + fail-fast: false + matrix: + compression: [gzip, deflate, zstd] + concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}-${{ matrix.compression }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + env: + HARNESS_IMAGE: ghcr.io/posthog/sdk-test-harness:1.31.1@sha256:f84d5c70dd72ea4436957ea6dbbc1f6836b6f6cbb472c749711d0f3659d85377 + steps: + - name: Check out source code + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Pull test harness + run: docker pull "$HARNESS_IMAGE" + + - name: Build SDK adapter + run: docker build -f sdk_compliance_adapter/Dockerfile -t sdk-adapter:test . + + - name: Start SDK adapter + run: | + docker network create test-network + docker run -d \ + --name sdk-adapter \ + --network test-network \ + -e COMPRESSION=${{ matrix.compression }} \ + sdk-adapter:test + + - name: Run compliance suite + run: | + mkdir -p report + docker run --rm \ + --name test-harness \ + --network test-network \ + -v "${GITHUB_WORKSPACE}/report:/report" \ + "$HARNESS_IMAGE" \ + run \ + --adapter-url http://sdk-adapter:8080 \ + --mock-url http://test-harness:8081 \ + --output text \ + --report /report/sdk-compliance-report.md \ + --sdk-type server + + - name: Publish report to the job summary + if: always() + run: | + if [ -f report/sdk-compliance-report.md ]; then + cat report/sdk-compliance-report.md >> "$GITHUB_STEP_SUMMARY" + fi + + - name: Upload compliance report + if: always() + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: sdk-compliance-report-${{ matrix.compression }} + path: report/sdk-compliance-report.md + + - name: Show adapter logs on failure + if: failure() + run: docker logs sdk-adapter || true + + - name: Stop containers + if: always() + run: | + docker rm -f sdk-adapter || true + docker network rm test-network || true diff --git a/.sampo/changesets/ai-blank-distinct-id-personless.md b/.sampo/changesets/ai-blank-distinct-id-personless.md new file mode 100644 index 000000000..f06b2f44f --- /dev/null +++ b/.sampo/changesets/ai-blank-distinct-id-personless.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: patch +--- + +AI integrations (LLM wrappers, embeddings, LangChain and OpenAI Agents) treat an empty or whitespace-only `distinct_id` as missing, as the client does: the event uses its trace or run ID and is personless. Before, an empty ID gave streaming calls, embeddings and LangChain the trace or run ID with person processing on, so PostHog created a person for each trace or run. Non-streaming wrapper calls used a random personless ID, and OpenAI Agents already treated an empty ID as missing. A whitespace-only ID was sent as given. diff --git a/.sampo/changesets/ai-integrations-require-capture-ai.md b/.sampo/changesets/ai-integrations-require-capture-ai.md new file mode 100644 index 000000000..8b4d4a478 --- /dev/null +++ b/.sampo/changesets/ai-integrations-require-capture-ai.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: major +--- + +The AI integrations no longer fall back to `capture` for a client object without `capture_ai`. Creating an OpenAI, Anthropic or Gemini wrapper, the LangChain `CallbackHandler`, or the OpenAI Agents or Claude Agent SDK processor with such a client now logs one error and captures no AI events. Provider calls still work. The error shows up when you set the integration up, and not after a provider call. A `Client` or `AsyncPosthog` instance, and the default global client, work as before. diff --git a/.sampo/changesets/ai-posthog-options.md b/.sampo/changesets/ai-posthog-options.md new file mode 100644 index 000000000..6c72874be --- /dev/null +++ b/.sampo/changesets/ai-posthog-options.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: minor +--- + +AI integrations take capture options. Every wrapper method that takes `posthog_properties` also takes `posthog_options` (OpenAI, Anthropic, Gemini, sync and async, and the Claude Agent SDK `query()` and `PostHogClaudeSDKClient`), and the Gemini clients take it as a default for every call. LangChain's `CallbackHandler` and `PostHogMiddleware`, and `instrument()` and the tracing processors for OpenAI Agents and the Claude Agent SDK, take `options=`. LangChain also reads `posthog_options` from run metadata. These options win over context options and `super_options`. An event without a distinct ID still always sends `process_person_profile: False`, and a value that is not a dict is logged and ignored. diff --git a/.sampo/changesets/async-exception-span-ids.md b/.sampo/changesets/async-exception-span-ids.md new file mode 100644 index 000000000..b4dd157be --- /dev/null +++ b/.sampo/changesets/async-exception-span-ids.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: minor +--- + +`AsyncPosthog.capture_exception` now adds the active OpenTelemetry span's `$trace_id` and `$span_id`, like `Client.capture_exception`, even when `capture_trace_context` is off. diff --git a/.sampo/changesets/call-disable-geoip-event-value.md b/.sampo/changesets/call-disable-geoip-event-value.md new file mode 100644 index 000000000..ae143d617 --- /dev/null +++ b/.sampo/changesets/call-disable-geoip-event-value.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: major +--- + +A `disable_geoip` argument to a call now counts as a value of that event. It wins over a `$geoip_disable` in context tags or `super_properties`, and a `$geoip_disable` in the call's own `properties` still wins over it. `disable_geoip=False` now sends `$geoip_disable: false`, so it turns GeoIP lookup on for that event even when a context tag or `super_properties` turns it off. The client's `disable_geoip` setting keeps its place below every caller value. `AsyncPosthog` follows the same rules. diff --git a/.sampo/changesets/capture-hook-log-and-connection-retries.md b/.sampo/changesets/capture-hook-log-and-connection-retries.md new file mode 100644 index 000000000..c17b13754 --- /dev/null +++ b/.sampo/changesets/capture-hook-log-and-connection-retries.md @@ -0,0 +1,9 @@ +--- +pypi/posthog: patch +--- + +Capture makes one connection try per attempt, so every physical request carries its own attempt number and request timestamp. posthog-python 7.x.x also retried a failed connection up to twice inside each attempt, reusing the request timestamp, which shifted the events' stored time by the time spent connecting. + +When `before_send` raises, the error line names the event and the exception type, not the exception message. The traceback is logged at debug level. + +Events without `NaN` or `Infinity` are encoded once, without first copying them to replace non-finite numbers. Events that contain them still send those values as `null`. diff --git a/.sampo/changesets/capture-retry-404-429.md b/.sampo/changesets/capture-retry-404-429.md new file mode 100644 index 000000000..7f72747c1 --- /dev/null +++ b/.sampo/changesets/capture-retry-404-429.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: patch +--- + +Capture retries `404` and `429` responses like `408` and `500`, `502`, `503`, `504`, with the same backoff and `Retry-After` handling. diff --git a/.sampo/changesets/capture-retry-jitter.md b/.sampo/changesets/capture-retry-jitter.md new file mode 100644 index 000000000..08e170ddb --- /dev/null +++ b/.sampo/changesets/capture-retry-jitter.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: patch +--- + +Capture retry waits now vary randomly by up to 25%, so many clients do not retry at the same moment. diff --git a/.sampo/changesets/capture-same-origin-redirects.md b/.sampo/changesets/capture-same-origin-redirects.md new file mode 100644 index 000000000..cd45470f0 --- /dev/null +++ b/.sampo/changesets/capture-same-origin-redirects.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: major +--- + +Capture follows a `307` or `308` redirect only to the origin of `host`, at most 5 times, for the sync and async clients. Any other redirect fails the batch and reaches `on_error`. In posthog-python 7.x.x the sync client followed redirects to any origin and resent the event batch there. diff --git a/.sampo/changesets/capture-timestamp-fraction.md b/.sampo/changesets/capture-timestamp-fraction.md new file mode 100644 index 000000000..a54ae0eaa --- /dev/null +++ b/.sampo/changesets/capture-timestamp-fraction.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: patch +--- + +Capture timestamps always have six fractional-second digits, even on a whole second: `2026-01-02T03:04:05.000000+00:00`, not `2026-01-02T03:04:05+00:00`. This applies to the event `timestamp`, the batch `created_at` and the `PostHog-Request-Timestamp` header. The `timestamp` that `before_send` receives has the same format. diff --git a/.sampo/changesets/capture-v1-major.md b/.sampo/changesets/capture-v1-major.md new file mode 100644 index 000000000..b34e2a802 --- /dev/null +++ b/.sampo/changesets/capture-v1-major.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: major +--- + +Capture v1 is the only capture path. Events and AI events send to the capture v1 endpoints, and the legacy v0 capture path is removed. See the [migration guide](https://github.com/PostHog/posthog-python/blob/main/docs/migration-7.x-to-8.0.md) for breaking changes. diff --git a/.sampo/changesets/celery-context-options.md b/.sampo/changesets/celery-context-options.md new file mode 100644 index 000000000..8f4dda567 --- /dev/null +++ b/.sampo/changesets/celery-context-options.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: minor +--- + +The Celery integration propagates context options from the publisher to the worker, like tags. Options set with `set_context_option` before a task is published apply to every event captured while the task runs. `propagate_context=False` sends none of them. diff --git a/.sampo/changesets/duplicate-event-uuid.md b/.sampo/changesets/duplicate-event-uuid.md new file mode 100644 index 000000000..5f4a13f77 --- /dev/null +++ b/.sampo/changesets/duplicate-event-uuid.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: patch +--- + +Capture keeps the first event for each uuid in a request and drops the later copies. `on_error` now reports each dropped copy in `CaptureError.drops` as `(uuid, "duplicate_event_uuid")`, and the SDK does not resend it. Each entry of `CaptureError.drops` is a `CaptureDroppedEvent` from `posthog.capture_send`, a tuple that also has `uuid` and `details` fields. `verdict_summary()` counts each drop by its own reason. diff --git a/.sampo/changesets/exception-level-and-reserved-properties.md b/.sampo/changesets/exception-level-and-reserved-properties.md new file mode 100644 index 000000000..9777d743b --- /dev/null +++ b/.sampo/changesets/exception-level-and-reserved-properties.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: major +--- + +`capture_exception` takes a `level=` argument on `Client`, `AsyncPosthog` and the module, which sets `$exception_level` (default `"error"`). Reserved exception properties passed in `properties`, such as `$exception_list` and `$exception_level`, are now ignored. In posthog-python 7.x.x they overrode the SDK's values with a `DeprecationWarning`. `AsyncPosthog.capture_exception` now sends `$exception_level`. diff --git a/.sampo/changesets/identity-and-context-rules.md b/.sampo/changesets/identity-and-context-rules.md new file mode 100644 index 000000000..293d7d870 --- /dev/null +++ b/.sampo/changesets/identity-and-context-rules.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: major +--- + +`group_identify` falls back to the context distinct ID and then to `$_` instead of a random ID, and no longer adds the context session ID. `alias()` no longer takes its target from the context distinct ID. Context tags and options now apply to `alias` and `group_identify`, but context tags, context options, `super_options` and `super_properties` do not set `process_person_profile` on identify-style events (`$identify`, `$create_alias`, `$merge_dangerously`, `$groupidentify`, `$set` and `$set_once`) whose distinct ID the SDK did not generate. Those events default to `True` unless the call sets it. An empty or whitespace-only `distinct_id` counts as missing, and generated personless distinct IDs are UUIDv7. `AsyncPosthog` follows the same rules. diff --git a/.sampo/changesets/invalid-events-and-sizes.md b/.sampo/changesets/invalid-events-and-sizes.md new file mode 100644 index 000000000..176007c1e --- /dev/null +++ b/.sampo/changesets/invalid-events-and-sizes.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: major +--- + +An invalid event no longer costs the rest of its batch. An event with a missing, empty or non-string name, or with a non-string `distinct_id` after `before_send`, is dropped locally, an event that cannot be serialized is dropped alone (a non-finite float such as `NaN` is still sent as `null`), and a property key JSON cannot represent is dropped from its event. The analytics per-event limit is now capture's 10 MiB request limit instead of 900 KiB. A personal API key (`phx_...`) disables the client like an empty key. The SDK's own log lines no longer include event content or invalid timestamp values. `AsyncPosthog` follows the same rules. diff --git a/.sampo/changesets/invalid-uuid-warning.md b/.sampo/changesets/invalid-uuid-warning.md new file mode 100644 index 000000000..d89614ea8 --- /dev/null +++ b/.sampo/changesets/invalid-uuid-warning.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: major +--- + +An invalid event `uuid` is still replaced with a generated one, but the SDK now logs one warning instead of an error, and the warning no longer includes the value. An empty string `uuid` counts as unset, so the SDK generates one without logging. `AsyncPosthog` follows the same rules. diff --git a/.sampo/changesets/lib-is-an-sdk-value.md b/.sampo/changesets/lib-is-an-sdk-value.md new file mode 100644 index 000000000..963751c3a --- /dev/null +++ b/.sampo/changesets/lib-is-an-sdk-value.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: major +--- + +Events send `$lib` and `$lib_version` as they are at send time, whoever set them. If no `$lib` is set in the call's `properties`, a context tag or `super_properties`, the SDK sets both to `posthog-python` and the installed version. If `$lib` is `posthog-python` and `$lib_version` is missing, the SDK fills in the version. A `$lib` that names another library is sent with whatever `$lib_version` it has, so set both when you override them. Only a non-empty string counts as set. In posthog-python 7.x.x the SDK overwrote a `$lib` or `$lib_version` set in a call or a context tag. `before_send` can still change or remove both, and `AsyncPosthog` follows the same rules. diff --git a/.sampo/changesets/mcp-event-options.md b/.sampo/changesets/mcp-event-options.md new file mode 100644 index 000000000..d04282679 --- /dev/null +++ b/.sampo/changesets/mcp-event-options.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: minor +--- + +MCP events take capture options. The `PostHogMCP` capture methods and `McpAnalytics.capture` take an `event_options` argument, and `MCPAnalyticsOptions(event_options=...)` sets options on every event `instrument()` captures automatically, from a function of `(request, extra)` like `event_properties`. An event without an identity still always sends `process_person_profile: False`. `PostHogMCP.capture()` keeps the core client's `options` argument. diff --git a/.sampo/changesets/mcp-keeps-sdk-identity.md b/.sampo/changesets/mcp-keeps-sdk-identity.md new file mode 100644 index 000000000..cf189ca82 --- /dev/null +++ b/.sampo/changesets/mcp-keeps-sdk-identity.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: major +--- + +MCP instrumentation no longer relabels the whole client. In posthog-python 7.x.x, `posthog.mcp.instrument()` and `PostHogMCP` changed `$lib` on every event the client sent, including the app's own, and the SDK name in its request headers, feature flag requests included. `instrument()` without a client relabeled the global client. Now only MCP analytics events report `posthog-python-mcp`, and everything else reports `posthog-python`. The label is set in each MCP event's own properties, so a `$lib` in `super_properties` no longer replaces it. `before_send` can. diff --git a/.sampo/changesets/openfeature-provider-posthog-8.md b/.sampo/changesets/openfeature-provider-posthog-8.md new file mode 100644 index 000000000..c91b6da50 --- /dev/null +++ b/.sampo/changesets/openfeature-provider-posthog-8.md @@ -0,0 +1,5 @@ +--- +pypi/openfeature-provider-posthog: minor +--- + +Supports posthog-python 8.x.x as well as 7.x.x. diff --git a/.sampo/changesets/request-keyword-only.md b/.sampo/changesets/request-keyword-only.md new file mode 100644 index 000000000..e4304df4e --- /dev/null +++ b/.sampo/changesets/request-keyword-only.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: major +--- + +The parameters after `path` in `posthog.request.post` and after `host` in `posthog.request.flags` are keyword-only. With `gzip` removed, a posthog-python 7.x.x call that passed them by position bound them to the wrong parameter. It now raises `TypeError`. diff --git a/.sampo/changesets/session-id-drop-warning.md b/.sampo/changesets/session-id-drop-warning.md new file mode 100644 index 000000000..2e1b5b0f6 --- /dev/null +++ b/.sampo/changesets/session-id-drop-warning.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: major +--- + +A `$session_id` or `$window_id` that is not a string is not sent, because capture v1 would reject the whole batch, and the SDK logs a warning for each one. The warning names the key and the value's type, not the value. `None` counts as unset and drops without a warning. An empty string is sent. In posthog-python 7.x.x these values were sent as properties. diff --git a/.sampo/changesets/trace-ids-as-sdk-values.md b/.sampo/changesets/trace-ids-as-sdk-values.md new file mode 100644 index 000000000..f103af11e --- /dev/null +++ b/.sampo/changesets/trace-ids-as-sdk-values.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: major +--- + +The `$trace_id` and `$span_id` that the SDK takes from the active OpenTelemetry span now fill after the call's `properties`, context tags and `super_properties`, and before `before_send`. A `$trace_id` or `$span_id` in a context tag or `super_properties` now replaces the span's IDs, and setting either key stops the SDK adding both. `AsyncPosthog` follows the same rules. diff --git a/AGENTS.md b/AGENTS.md index 31dfbfb4b..0b983a313 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,7 +24,7 @@ Follow [Public API changes](./CONTRIBUTING.md#public-api-changes). As an agent, Before changing capture configuration, serialization, routing, or retries, read the relevant implementation and tests. -Preserve v0 defaults/compatibility; strictly typed v1 options and `$set`/`$set_once` relocation; v1-only compression (zlib-wrapped deflate, optional zstd); partial-only per-event retries with stable identity; accumulated drop reporting even on 2xx; v1 retries on `404` and `429` like `408` and 5xx; `Retry-After` as a minimum bounded by the shared 30s ceiling; and inline blocking retries with `sync_mode=True`. +Capture v1 is the only capture protocol (`capture` posts to `/i/v1/analytics/events`, `capture_ai` to `/i/v1/ai/events`); per-event `options` sent as given, layered over `super_options` and context options, with legacy `$` option properties hoisted once after `before_send` (identify-style events instead resolve `process_person_profile` from the call before any layer, default it to `true` unless the SDK generated the distinct ID, and drop `$process_person_profile` before `before_send` once the option is set); `$set`/`$set_once` relocation; compression (gzip, zlib-wrapped deflate, optional zstd, default none), set per lane by `capture_compression` and `capture_ai_compression`; partial-only per-event retries with stable identity; accumulated drop reporting even on 2xx; terminal v1 `429`; `Retry-After` as a minimum bounded by the shared 30s ceiling; and inline blocking retries with `sync_mode=True`. ## Mirror and build safety diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6a8503e90..b7534e642 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,7 +18,7 @@ uv sync --extra dev --extra test ## CI-aligned checks -Run the smallest relevant tests first, for example `pytest posthog/test/test_capture_v1.py --timeout=30` for v1 transport changes. Then run these core CI-aligned checks from the repository root in the activated `.venv` populated by the setup commands above: +Run the smallest relevant tests first, for example `pytest posthog/test/test_capture_send.py --timeout=30` for v1 transport changes. Then run these core CI-aligned checks from the repository root in the activated `.venv` populated by the setup commands above: ```bash ruff format --check . diff --git a/README.md b/README.md index cd92d38b6..45e58b436 100644 --- a/README.md +++ b/README.md @@ -18,17 +18,21 @@ SDK usage examples and code snippets live in the official documentation so they | SDK Version | Python Versions Supported | Notes | | ------------- | ---------------------------- | -------------------------- | -| 7.3.1+ | 3.10, 3.11, 3.12, 3.13, 3.14 | Added Python 3.14 support | +| 8.0.0+ | 3.10, 3.11, 3.12, 3.13, 3.14 | Capture v1 only | +| 7.3.1 - 7.x.x | 3.10, 3.11, 3.12, 3.13, 3.14 | Added Python 3.14 support | | 7.0.0 - 7.0.1 | 3.10, 3.11, 3.12, 3.13 | Dropped Python 3.9 support | -| 4.0.1 - 6.x | 3.9, 3.10, 3.11, 3.12, 3.13 | Python 3.9+ required | +| 4.0.1 - 6.x.x | 3.9, 3.10, 3.11, 3.12, 3.13 | Python 3.9+ required | + +To upgrade from posthog-python 7.x.x to 8.0.0, see the [migration guide](docs/migration-7.x-to-8.0.md). ## Documentation - [Python library docs](https://posthog.com/docs/libraries/python) +- [Migrating from posthog-python 7.x.x to 8.0.0](docs/migration-7.x-to-8.0.md) - [Django framework docs](https://posthog.com/docs/libraries/django) - [Flask framework docs](https://posthog.com/docs/libraries/flask) -- [Request integration configuration](references/middleware_configuration.md) — shared middleware options and compatibility notes -- [OpenFeature provider docs](https://posthog.com/docs/feature-flags/installation/openfeature) — use PostHog flags through the [OpenFeature](https://openfeature.dev) Python SDK +- [Request integration configuration](references/middleware_configuration.md), with shared middleware options and compatibility notes +- [OpenFeature provider docs](https://posthog.com/docs/feature-flags/installation/openfeature), to use PostHog flags through the [OpenFeature](https://openfeature.dev) Python SDK ## Contributing diff --git a/benchmarks/README.md b/benchmarks/README.md index d428c862e..dfa275058 100644 --- a/benchmarks/README.md +++ b/benchmarks/README.md @@ -71,7 +71,7 @@ Capture fixtures are preconstructed outside measurement: event `benchmark`, iden - `capture.drain.steady.*` and `capture.drain.burst.*` record `completion_boundary=completed_delivery`. Steady flushes every 100 captures; burst flushes once after all captures. Parameters record `drain_strategy` and `flush_every`. Both include `flush(timeout_seconds=None)` and reports the complete delivery path's process CPU and allocations, including requests/serialization. The external worker timeout bounds this wait. Verification does not flush again: unfinished measured work cannot be rescued outside the measurement. Server CPU and server allocations are excluded; elapsed time includes loopback transport. - Enqueue-only allocation metrics are explicitly unavailable and direct readers to the drain workload. -Capture uses public options `gzip=False`, `capture_mode="v0"`, `max_queue_size=100001`, `flush_at=100000`, and one-hour flush/poll intervals. The native consumer and size-driven batching remain active: burst describes the caller flush schedule, not retained queue size or a guaranteed HTTP request count. These metrics describe their named paths rather than pretending Python and Node have identical asynchronous lifecycles. +Capture sends uncompressed capture v1 requests and uses public options `max_queue_size=100001`, `flush_at=100000`, and one-hour flush/poll intervals. The native consumer and size-driven batching remain active: burst describes the caller flush schedule, not retained queue size or a guaranteed HTTP request count. These metrics describe their named paths rather than pretending Python and Node have identical asynchronous lifecycles. ## Measurement methods diff --git a/benchmarks/run.py b/benchmarks/run.py index f3eca2d4c..ae6f4e1be 100644 --- a/benchmarks/run.py +++ b/benchmarks/run.py @@ -75,7 +75,6 @@ def worker_env(): PYTHONHASHSEED="0", PYTHONNOUSERSITE="1", PYTHONDONTWRITEBYTECODE="1", - POSTHOG_CAPTURE_MODE="v0", ) return env @@ -375,7 +374,7 @@ def main(args=None): "file_format": "ALL_ALLOCATIONS", "scope": "PYMALLOC_MALLOC/CALLOC/REALLOC requests; all worker threads", }, - "transport": "loopback HTTP receiver in coordinator process; uncompressed v0", + "transport": "loopback HTTP receiver in coordinator process; uncompressed capture v1", "warmup": "two refreshes; otherwise min(operations, 32 for 1000 flags or 160); verified phase reset before measurement", "settling": "two gc.collect calls separated by sleep(0)", "memory_sampling": "operation checkpoints; lifetime high-water mark includes setup and warmup", diff --git a/benchmarks/server.py b/benchmarks/server.py index b119c2ff9..534eec070 100644 --- a/benchmarks/server.py +++ b/benchmarks/server.py @@ -102,7 +102,9 @@ def do_POST(self): definitions(spec["flag_count"], generation) ).encode() self.reply(200, b"{}") - elif path == "/batch": + # /batch serves the merge-base SDK in a paired run, which + # still posts legacy batches; this SDK posts capture v1. + elif path in ("/batch", "/i/v1/analytics/events"): if batch_delay: time.sleep(batch_delay) batch = body["batch"] @@ -136,7 +138,18 @@ def do_POST(self): owner.seen[sequence] = 1 owner.state["unique_sequences"] += 1 owner.state["missing_sequences"] -= 1 - self.reply(200, b'{"status":1}') + if path == "/batch": + self.reply(200, b'{"status":1}') + else: + # Capture v1 reports a result per event uuid; anything + # else is an unreadable response to the SDK. + results = { + str(event.get("uuid")): {"result": "ok"} + for event in batch + } + self.reply( + 200, json.dumps({"results": results}).encode() + ) else: self.unexpected(path) except (ValueError, KeyError, TypeError, AttributeError): diff --git a/benchmarks/test_benchmarks.py b/benchmarks/test_benchmarks.py index af51f4115..dcfd89b46 100644 --- a/benchmarks/test_benchmarks.py +++ b/benchmarks/test_benchmarks.py @@ -364,8 +364,16 @@ def flush(self, timeout_seconds=10, _calls=calls, _submitted=submitted): def test_balanced_duplicate_loss_fails_and_delivery_order_is_not_required(self): spec = next(s for s in workloads(True) if s["id"] == "capture.drain.burst.32") - for duplicate in (False, True): - with self.subTest(duplicate=duplicate), BenchmarkServer(spec) as server: + # The merge-base SDK in a paired run posts to /batch; this SDK posts to capture v1. + for route, duplicate in [ + (route, duplicate) + for route in ("/batch", "/i/v1/analytics/events") + for duplicate in (False, True) + ]: + with ( + self.subTest(route=route, duplicate=duplicate), + BenchmarkServer(spec) as server, + ): workload = Workload(spec, server.url) try: events = workload.events @@ -373,7 +381,23 @@ def test_balanced_duplicate_loss_fails_and_delivery_order_is_not_required(self): # Replace the final 16 events with the preceding 16: total and # per-identity counts stay identical, but sequences do not. events = events[:-16] + events[-32:-16] - control(server.url, "/batch", {"batch": list(reversed(events))}) + reply = control( + server.url, + route, + {"batch": list(reversed(events))}, + ) + if route == "/batch": + self.assertEqual(reply, {"status": 1}) + else: + self.assertEqual( + reply, + { + "results": { + str(event.get("uuid")): {"result": "ok"} + for event in events + } + }, + ) workload.captured = spec["operations"] for event in workload.events: workload.captured_by_user[event["distinct_id"]] += 1 diff --git a/benchmarks/workload.py b/benchmarks/workload.py index 570cde328..c8411f41d 100644 --- a/benchmarks/workload.py +++ b/benchmarks/workload.py @@ -38,8 +38,6 @@ def __init__(self, spec, host, client_class=None): timeout=5, max_retries=0, feature_flags_request_max_retries=0, - gzip=False, - capture_mode="v0", thread=1, on_error=lambda error, _batch: self.errors.append(str(error)), **({"personal_api_key": "benchmark-local-only"} if self.flags else {}), diff --git a/bin/docs_scripts/generate_markdown.py b/bin/docs_scripts/generate_markdown.py index 8ade17f58..9f7237aea 100644 --- a/bin/docs_scripts/generate_markdown.py +++ b/bin/docs_scripts/generate_markdown.py @@ -214,6 +214,26 @@ def nest(markdown: str) -> str: return "\n".join(out) +def migration_page(guides: list[str]) -> list[str]: + """The migration page. One guide's H1 becomes the page title, so the page shows one title.""" + title = "PostHog Python SDK migration guides" + if len(guides) == 1 and guides[0].startswith("# "): + heading, _, rest = guides[0].partition("\n") + title, guides = heading[2:].strip(), [rest.strip()] + head = f"---\ntitle: {json.dumps(title)}\nsidebar: Docs\nshowTitle: true\n---" + return [head, *guides] + + +def getting_started(major: int) -> str: + """docs/getting-started.md for one major. Its install line pins that major, so a + reader never installs a major the page doesn't describe.""" + text = (ROOT / "docs/getting-started.md").read_text() + if "{major}" not in text: + raise SystemExit("docs/getting-started.md: the install line must pin {major}") + pinned = text.replace("{major}", str(major)) + return nest(pinned.replace("{next_major}", str(major + 1))) + + def write(name: str, sections: list[str]) -> None: (ROOT / "references" / name).write_text("\n\n".join(sections) + "\n") print(f"wrote references/{name}") @@ -239,15 +259,13 @@ def main() -> None: (ROOT / "posthog/version.py").read_text().split('"')[1].split(".")[0] ) major = opts.major or declared - started = nest((ROOT / "docs/getting-started.md").read_text()) + started = getting_started(major) body = [ "## Getting started", started, *reference(pkg, capabilities(opts.sdk_specs), declared >= major), ] - title = f"PostHog Python SDK {major}.x" + ( - "" if declared >= major else " (experimental)" - ) + title = f"PostHog Python SDK {major}.x" write(f"posthog-python-{major}.md", [front_matter(title, body), *body]) if declared >= major: write( @@ -255,10 +273,9 @@ def main() -> None: [front_matter("PostHog Python SDK", body), *body], ) if guides := sorted((ROOT / "docs").glob("migration-*.md"), reverse=True): - head = "---\ntitle: PostHog Python SDK migration guides\nsidebar: Docs\nshowTitle: true\n---" write( "posthog-python-migration.md", - [head, *(g.read_text().strip() for g in guides)], + migration_page([g.read_text().strip() for g in guides]), ) diff --git a/docs/getting-started.md b/docs/getting-started.md index 27d91f176..5b71d213f 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -7,7 +7,7 @@ To send your first event, install the package, create a client, capture an event ## Install ```bash -pip install posthog +pip install "posthog>={major},<{next_major}" ``` ## Initialize @@ -37,3 +37,26 @@ posthog.shutdown() ``` In an asyncio app, use `AsyncPosthog` as an async context manager instead. See [AsyncClient](#asyncclient). + +## Use AsyncPosthog in FastAPI + +Keep one `AsyncPosthog` client for the lifetime of your app. A FastAPI lifespan handler does this. + +```python +from contextlib import asynccontextmanager + +from fastapi import FastAPI +from posthog import AsyncPosthog + +@asynccontextmanager +async def lifespan(app: FastAPI): + async with AsyncPosthog("", host="") as posthog: + app.state.posthog = posthog + yield + +app = FastAPI(lifespan=lifespan) +``` + +## The posthoganalytics package + +`posthoganalytics` is the same SDK under another module name. Use it when another module named `posthog` is on your import path. diff --git a/docs/migration-7.x-to-8.0.md b/docs/migration-7.x-to-8.0.md new file mode 100644 index 000000000..f0e0edf2e --- /dev/null +++ b/docs/migration-7.x-to-8.0.md @@ -0,0 +1,495 @@ +# Migrate the Python SDK from 7.x.x to 8.0.0 + +The Python SDK 8.x.x sends every event to the [capture v1](https://posthog.com/docs/api/capture-v1) endpoints, `/i/v1/analytics/events` and `/i/v1/ai/events`, and removes the legacy capture path. Most apps upgrade without code changes. + +Use the top right copy page button to work through this with your agents. + +You don't need to make every change on the day you upgrade your SDK. Required changes fall in these categories: + +- **Before you upgrade**: you should make these changes before you upgrade your SDK to 8.x.x. +- **During your upgrade**: These are changes that you need to make in the same PR that upgrades your SDK version. +- **Follow ups**: These are changes that can come in follow up PRs because 8.x.x has limited backward compatibility for methods that are to be deprecated. + +## Checklist + +Read the checklist first, then the sections that apply to you. + +**Before you upgrade** + +- [ ] You send events through your own proxy → [Prepare your proxy](#prepare-your-proxy) +- [ ] A proxy redirects capture requests to another host → [Prepare your proxy](#prepare-your-proxy) +- [ ] You pass a personal API key (`phx_...`) as the project token → [Use a project token](#use-a-project-token) +- [ ] You use `openfeature-provider-posthog` below 0.2.0 → [Update OpenFeature](#update-openfeature) + +**During your upgrade** + +- [ ] You pass `Client` or `AsyncPosthog` constructor arguments by position after `host` → [Fix removed APIs](#fix-removed-apis) +- [ ] You call `posthog.request.post` or `posthog.request.flags` with positional arguments after `path` or `host` → [Fix removed APIs](#fix-removed-apis) +- [ ] You set `capture_mode`, `POSTHOG_CAPTURE_MODE`, or `gzip` → [Fix removed APIs](#fix-removed-apis) +- [ ] You import `CaptureMode`, `posthog.capture_mode`, `CaptureV1Error`, `posthog.capture_v1`, `request.batch_post`, `EVENTS_ENDPOINT`, or `AI_EVENTS_ENDPOINT` → [Fix removed APIs](#fix-removed-apis) +- [ ] Your `before_send` hook returns a new dict, in the client or in MCP → [Copy options in before_send](#copy-options-in-before_send) +- [ ] You test the AI integrations with a mock client and assert on `capture` → [Route AI events](#route-ai-events) +- [ ] You pass your own client object to the AI integrations → [Route AI events](#route-ai-events) +- [ ] You call `alias()` without a `distinct_id` and rely on the context distinct ID → [Fix identity calls](#fix-identity-calls) +- [ ] You turn person processing off with `super_options`, `super_properties`, a context option, or a context tag, and expect identify-style events, such as those from `alias`, `group_identify`, `set`, or `set_once`, to follow it → [Fix identity calls](#fix-identity-calls) +- [ ] You reuse one event `uuid` for more than one event → [Check event IDs](#check-event-ids) +- [ ] You expect `super_properties` to override a call's properties, including `$set` and `$groups` → [Check property precedence](#check-property-precedence) +- [ ] You set `$is_server`, `$geoip_disable`, or a system property such as `$os`, and expect the SDK's value to win → [Check property precedence](#check-property-precedence) +- [ ] You set `$lib` or `$lib_version` yourself → [Check SDK identity](#check-sdk-identity) +- [ ] An insight or dashboard filters on `$lib = posthog-python-mcp` → [Check SDK identity](#check-sdk-identity) +- [ ] You read event content from the SDK's debug log, or alert on SDK log lines → [Update error handling](#update-error-handling) +- [ ] You set `$exception_level` or another reserved exception property in `capture_exception(properties=...)` → [Check exceptions](#check-exceptions) +- [ ] You run the Django, Flask, or ASGI integration on 7.68.x to 7.70.x without tracing headers turned on → [Check tracing headers](#check-tracing-headers) + +**Follow ups** + +- [ ] You set legacy option properties like `$process_person_profile` → [Move to event options](#move-to-event-options) +- [ ] You capture `$ai_` events with `capture()` → [Send AI events with capture_ai](#send-ai-events-with-capture_ai) +- [ ] You use `trust_tracing_headers` or `_use_ai_lane`, set `posthog.capture_mode`, or pass a `gzip=` keyword to `request.post` → [Rename deprecated settings](#rename-deprecated-settings) + +## Before you upgrade + +### Prepare your proxy + +8.x.x sends events to these endpoints: + +| Method | Endpoint | +| --- | --- | +| `capture`, `set`, `set_once`, `alias`, `group_identify`, `capture_exception`, `AsyncPosthog.capture_immediate` | `/i/v1/analytics/events` | +| `capture_ai`, `capture_ai_immediate`, and the AI wrapper integrations | `/i/v1/ai/events` | +| OpenTelemetry (`posthog.ai.otel`) | `/i/v0/ai/otel`, unchanged | + +If you send events through your own reverse proxy, update it before you upgrade: + +- **Forward both routes.** Forward `/i/v1/analytics/events` and `/i/v1/ai/events` to PostHog. +- **Pass the headers through unchanged.** Pass `Authorization`, every `PostHog-*` header, `Content-Type`, `Content-Encoding`, and `User-Agent`. `Authorization` holds the project token, sent as `Bearer `. PostHog answers `401` without `Authorization` and `400` without the others, and the batch fails. +- **Accept request bodies up to 20 MB.** AI requests are often larger than 1 MB, the default limit in nginx and ingress-nginx. A `413` from the proxy fails the batch. +- **Pass the capture response through.** Return PostHog's status code and response body unchanged. A proxy that answers the capture path with its own `200` fails the batch. + +PostHog's managed reverse proxy already does this. See the [proxy guides](https://posthog.com/docs/advanced/proxy). + +The SDK follows a `307` or `308` redirect only to the origin of `host`, at most 5 times. The origin is the same scheme, host, and port. + +Any other redirect fails the batch and reaches `on_error`. In 7.x.x the sync client followed redirects to any origin. + +If a proxy redirects capture requests to another host, point `host` at the final host. + +### Use a project token + +A personal API key (`phx_...`) passed as the project token disables the client and logs one error, as an empty key does. Capture rejects personal API keys, and the SDK no longer sends one with every request. + +### Update OpenFeature + +`openfeature-provider-posthog` 0.2.0 works with `posthog` 7.x.x and 8.x.x. Older provider versions require `posthog` below 8.0.0, so upgrade the provider before or with `posthog`. + +## During your upgrade + +### Fix removed APIs + +8.x.x removes these options and APIs: + +| Removed | Use instead | +| --- | --- | +| `capture_mode`, `CaptureMode`, `POSTHOG_CAPTURE_MODE` | Nothing | +| `gzip=True` | `capture_compression` | +| `CaptureV1Error` | `CaptureError` | +| `posthog.capture_v1` | `posthog.capture_event` and `posthog.capture_send` | +| `request.batch_post`, `async_batch_post`, `EVENTS_ENDPOINT`, `AI_EVENTS_ENDPOINT` | Send events through a client | +| The `gzip` parameter of `request.post` and `request.flags` | Nothing | +| The `backoff` dependency | Your own requirements, if your code imports it | + +Capture v1 is the only path. Setting `posthog.capture_mode` on the module has no effect. + +For gzip, set `capture_compression=CaptureCompression.GZIP`. `capture_compression` defaults to no compression. `POSTHOG_CAPTURE_COMPRESSION` still works. + +`capture_compression` and `capture_ai_compression` take `CaptureCompression.GZIP`, `DEFLATE`, or `ZSTD`. `ZSTD` needs the `zstandard` package, so install `posthog[zstd]`. Without it, the client raises `ValueError`. + +Replace `from posthog.capture_v1 import CaptureV1Error` with `from posthog import CaptureError`. There is no alias. + +The parameters after `path` in `request.post` and after `host` in `request.flags` are keyword-only, so a 7.x.x call that passes them by position raises `TypeError`. A `gzip=` keyword raises no error. It's sent as a field in the request body. + +The `posthoganalytics` package has the same changes. For example, import `CaptureError` from `posthoganalytics`. + +Constructor arguments after `host` are keyword-only: + +```python +# 7.x.x +Posthog("", "https://us.i.posthog.com", True) + +# 8.x.x +Posthog("", host="https://us.i.posthog.com", debug=True) +``` + +### Copy options in before_send + +Review your `before_send` hooks for the new event shape. Capture v1 sends processing options in an `options` object, next to `properties`. + +To change an option, edit `options`. A hook that returns a new dict must copy `options`, or the event is sent without them. + +That includes the `process_person_profile = false` the SDK sets for an event without a distinct ID. Without it, PostHog would create a person for the event's generated ID. + +A hook that builds an identify-style event, or renames an event to one, must set the `process_person_profile` option itself (see [Fix identity calls](#fix-identity-calls)). + +A hook that spreads the event into the new dict keeps `options`: + +```python +def remove_email(event): + properties = {key: value for key, value in event["properties"].items() if key != "email"} + return {**event, "properties": properties} +``` + +The same applies to MCP's `before_send`. It gets each event's `options` in an `options` key of `PostHogCaptureEvent`. + +An MCP hook that returns a new dict must copy them, or the event is sent without the anonymous `process_person_profile: False`. + +### Route AI events + +8.x.x routes AI events to their own endpoint: + +- **The endpoint.** `capture_ai` and the AI wrapper integrations send to `/i/v1/ai/events`. The AI endpoint accepts events up to 8 MiB. +- **Event names.** `capture_ai` sends any event name to the AI endpoint. PostHog drops an event whose name doesn't start with `$ai_` as `misrouted_event`, and `on_error` reports it. The SDK writes only a debug log. +- **Custom clients.** The AI integrations call your client's `capture_ai`, and never `capture`. A custom client object must implement `capture_ai` and accept its `options` keyword argument. +- **Clients without `capture_ai`.** The wrapper, callback handler, or tracing processor logs one error when you create it and captures no AI events. Provider calls still work. Before, such a client got `capture` calls. +- **Mock clients.** Tests that pass a `Mock` client to an AI integration must assert on `mock.capture_ai`, not `mock.capture`. +- **OpenTelemetry.** The OpenTelemetry integration (`PostHogSpanProcessor`, `PostHogTraceExporter`) is unchanged. It still exports spans over OTLP to `/i/v0/ai/otel`. +- **Content capture.** `enable_full_ai_capture` now controls only content: string truncation and media redaction. It no longer chooses the endpoint. +- **Fallback IDs.** When an AI integration or MCP falls back to a trace, run, or session ID, it turns person processing off with a per-event option. This is the only option the integrations set on their own. It wins over your `posthog_options`, `options`, `super_options`, and context options. `before_send` can still change it. +- **Empty distinct IDs.** An empty or whitespace-only distinct ID passed to an AI integration, such as `posthog_distinct_id=""`, counts as missing. The integration falls back the same way and turns person processing off. +- **Empty distinct IDs in 7.x.x.** An empty ID gave non-streaming wrapper calls a random personless ID. Streaming calls, embeddings, and LangChain used the trace or run ID with person processing on. OpenAI Agents already treated an empty ID as missing. Every integration sent a whitespace-only ID as given, with person processing on. +- **Async capture.** `AsyncPosthog` has `capture_ai` and `capture_ai_immediate`. It sends events with `requests` in a worker thread, and uses `httpx` only for feature flags and remote config. +- **Async content settings.** `AsyncPosthog` accepts `privacy_mode` and `enable_full_ai_capture`, with the same meaning as on `Client`. An AI integration given an `AsyncPosthog` client used to always truncate and redact media. + +`Client` and `AsyncPosthog` have new arguments for the AI lane: + +| Argument | Default | +| --- | --- | +| `capture_ai_compression` | No compression | +| `capture_ai_max_queue_size` | 1000 | +| `capture_ai_timeout` | 30 seconds | +| `capture_ai_max_event_bytes` | 8 MiB plus 64 KiB | + +`POSTHOG_CAPTURE_COMPRESSION` doesn't apply to `capture_ai_compression`. You can only lower `capture_ai_max_event_bytes`. + +The AI lane doesn't use `max_queue_size`, `timeout`, or `capture_compression`. An invalid `capture_ai_*` value raises `ValueError` when you create the client. + +The module-level client has no AI lane settings. To change them, create a `Client`. + +### Fix identity calls + +- **Empty IDs.** An empty or whitespace-only `distinct_id` counts as missing, so the event gets a generated personless distinct ID. 7.x.x sent a whitespace-only ID, and capture dropped the event. +- **Generated IDs.** Generated personless distinct IDs are UUIDv7. 7.x.x generated UUIDv4. +- **Group fallback.** `group_identify` uses the `distinct_id` you pass, then the context distinct ID, then `$_`. 7.x.x fell back to a random ID, which created a new person on every call. +- **Long group IDs.** If `$_` is over 200 bytes, pass `distinct_id`. PostHog drops an event whose distinct ID is over 200 bytes. +- **Long distinct IDs.** PostHog drops an event whose `distinct_id` is over 200 UTF-8 bytes (`distinct_id_too_large`), and `on_error` reports it. 7.x.x sent events to legacy capture, which shortened the ID to 200 characters and kept the event. +- **Group sessions.** `group_identify` no longer adds the context session ID. A session takes the person of its latest event, and this event's distinct ID isn't the session's user. +- **Alias.** `alias()` needs an explicit `distinct_id`. It no longer falls back to the context distinct ID, which can come from a request header the client controls. Without one, the SDK drops the call with a warning. +- **Context values.** Context tags and context options now apply to `alias` and `group_identify`, below the call's own values, as they do for `capture`. + +Identify-style events default to person processing on. These are `$identify`, `$create_alias`, `$merge_dangerously`, `$groupidentify`, `$set`, and `$set_once`, whether `alias`, `group_identify`, `set`, `set_once`, `capture`, or `capture_ai` sends them. + +The SDK sets `process_person_profile: True` on them unless the call sets the `process_person_profile` option, a `capture` or `capture_ai` call sets a `$process_person_profile` property, or the SDK generated the distinct ID. PostHog drops the `$create_alias` and `$groupidentify` events when person processing is off, with an ingestion warning, and ignores the person update of `$set` and `$set_once`. + +- **Call values.** The call's own value wins over context options and tags, `super_options`, and `super_properties`. So a `False` set there never reaches these events when the SDK didn't generate the distinct ID. In 7.x.x, `$process_person_profile: False` in `super_properties` reached them too. +- **Legacy property.** When a `capture` or `capture_ai` call sets only the `$process_person_profile` property, the SDK moves it into the option. The `properties` of `set`, `set_once`, and `group_identify` are person and group properties, so pass `process_person_profile` in the call's `options`. +- **`None` values.** A `None` option or property counts as unset here, so the event gets `True`. +- **Generated IDs.** An event whose distinct ID the SDK generated gets no default. Context options and `super_options` still fill it, then the personless `process_person_profile: False`. +- **`before_send`.** The hook sees the value and can change it. The SDK first removes any `$process_person_profile` property from these events, including one from a context tag or `super_properties`, so the hook sees only the option. +- **Built events.** A hook that builds an identify-style event, or renames an event to one, must set the option itself. + +To keep one of these events personless, set `process_person_profile: False` on the call or in `before_send`, or turn off person processing for the project in PostHog. + +### Check event IDs + +- **Duplicates.** Each event needs its own UUID. Capture keeps the first event for each UUID in a request and drops the later copies. `on_error` reports each dropped copy in `CaptureError.drops` as `(uuid, "duplicate_event_uuid")`. 7.x.x sent every copy. Older PostHog versions reject the whole batch with a 400 `duplicate_event_uuid` instead. +- **Accepted forms.** The SDK accepts a UUID with hyphens, 32 hex digits, `{...}` braces, or a `urn:uuid:` prefix, in any case. It sends the lowercase hyphenated form and returns that form from `capture`. +- **Other values.** The SDK replaces any other value with a generated UUID. It logs one warning that names the rule, not the value. An empty string counts as unset, so the SDK generates a UUID without a warning. This applies to `AsyncPosthog` too. +- **Generated UUIDs.** Generated UUIDs are UUIDv7. + +### Check property precedence + +An event's options and properties come from five steps, in this order. Steps 2 to 4 fill only the options and properties that the steps before them left unset: + +1. The `options` and `properties` of the call, then the call's `disable_geoip` argument, which fills `$geoip_disable`. An identify-style event also gets `process_person_profile: True` here when the call leaves it unset and the SDK didn't generate its distinct ID (see [Fix identity calls](#fix-identity-calls)). +2. Context options and tags. +3. `super_options` and `super_properties`. +4. Values the SDK sets: + - `$lib` and `$lib_version` as a pair (see [Check SDK identity](#check-sdk-identity)) + - `$is_server` from `is_server` + - `$geoip_disable` from the client's `disable_geoip` setting + - System properties such as `$os` and `$python_version` + - The `$feature/` and `$active_feature_flags` properties from `flags` or `send_feature_flags` + - `$trace_id` and `$span_id` from the active OpenTelemetry span (in `capture` and `capture_ai` only with `capture_trace_context=True`, and always in `capture_exception`) + - `options.process_person_profile = false` for events without a distinct ID + - `$release_id` from `POSTHOG_RELEASE_ID` +5. `before_send`, which sees the result of steps 1 to 4 and can change or remove any of it. + +A property set to `None` counts as set, so no later step fills it. A `None` option counts as unset, so a later step can fill it. + +`$lib` and `$lib_version` are the exception. They count as set only when they're non-empty strings (see [Check SDK identity](#check-sdk-identity)). + +`$set`, `$set_once`, `$groups`, and `$group_set` fill one level deep. When the call and a later step both set one of them to a dict, the later step adds only the keys the call left out. + +For example, `super_properties={"$set": {"plan": "free", "source": "web"}}` and a call with `properties={"$set": {"plan": "pro"}}` send `{"plan": "pro", "source": "web"}`. A `$set` in `super_properties` or a context tag sets those person properties on every event it reaches. + +These changes follow from this order: + +- **Call properties.** Properties passed to a call now override `super_properties`. +- **SDK values.** A `$is_server`, `$geoip_disable`, `$lib`, `$lib_version`, or system property such as `$os` that you set in a call or a context tag now wins over the SDK's value. In 7.x.x the SDK overwrote it. +- **SDK values and `super_properties`.** `super_properties` win over the SDK's value too. So `super_properties={"$geoip_disable": False}` turns GeoIP lookup on for events, even with `disable_geoip=True`. So does `None`, in the event's properties, a context tag or `super_properties`: a `None` property counts as set, so the SDK adds no `True`. +- **Feature flag properties.** Feature flag properties from `flags` or `send_feature_flags` still lose to the same key in the call's `properties`, a context tag, or `super_properties`, as in 7.x.x. +- **Trace IDs.** A `$trace_id` or `$span_id` in a context tag or `super_properties` now replaces the active OpenTelemetry span's IDs. In 7.x.x the span's IDs beat context tags. +- **Trace ID pairs.** Setting either key in the call's `properties`, a context tag, or `super_properties` stops the SDK adding both. In 7.x.x the SDK still added the other key. +- **The `disable_geoip` argument.** A `disable_geoip` argument to a call belongs to that event, so it wins over context tags and `super_properties`. A `$geoip_disable` in the call's own `properties` still wins over it. +- **`disable_geoip=False`.** It now sends `$geoip_disable: false`. In 7.x.x it sent no `$geoip_disable` property. +- **The `groups` argument.** It merges into a `$groups` property of the call, and wins key by key. In 7.x.x it replaced the property. MCP events merge their identity's groups into a custom `$groups` property the same way. +- **Merged dicts.** A `$set`, `$set_once`, `$groups`, or `$group_set` in `super_properties` no longer replaces the whole value of the call. The two merge, and the call wins key by key. +- **Events without a distinct ID.** An event without a distinct ID gets `options.process_person_profile = false`. To turn person processing on for it, set the `process_person_profile` option. +- **Minimal flag events.** When the server enables minimal `$feature_flag_called` events, those events now keep `$window_id`. Their options still apply, because the trim removes only properties. + +### Check SDK identity + +By default every event carries `$lib: "posthog-python"` and the installed package version in `$lib_version`. PostHog stores the values the event is sent with. + +You can set them in a call's `properties`, a context tag, or `super_properties`. Like any other property, each one comes from the most specific place that sets it, so set both in the same place. + +`$lib` and `$lib_version` count as set only when they're non-empty strings. `before_send` sees both and can change or remove them. + +If you set `$lib` without `$lib_version`, the SDK adds its own version only when `$lib` is `posthog-python`. The SDK replaces a `$lib_version` that has no `$lib` with its own. + +| You set | 8.x.x sends | 7.x.x sent | +| --- | --- | --- | +| `$lib` or `$lib_version` in a call or a context tag | Your value | The SDK's value | +| `super_properties={"$lib": "my-lib"}` | No `$lib_version` | The SDK version | +| `super_properties={"$lib_version": "1.0"}` without a `$lib` | The SDK's `$lib` and version | `1.0` | + +If an event reaches PostHog without `$lib`, PostHog fills both from the SDK name and version your request sends. If `$lib` is that SDK name and `$lib_version` is missing, empty, or not a string, PostHog fills `$lib_version` the same way. + +MCP analytics events from `posthog.mcp.instrument()` or `PostHogMCP` report `posthog-python-mcp` and the installed package version. The integration sets both in each event's own properties, so neither a context tag nor `super_properties` replaces them, but `before_send` can. + +In 7.x.x the MCP integration relabeled the whole client, or the default client when `instrument()` got none. That covered the app's own events, the request headers, and feature flag requests. + +In 8.x.x those report `posthog-python`, so one client can serve both. + +Custom events from `PostHogMCP.capture()` now report `posthog-python`. In 7.x.x they reported `posthog-python-mcp`. + +Custom events from `McpAnalytics.capture()`, the handle `instrument()` returns, still report `posthog-python-mcp`. If an insight or dashboard filters on `$lib = posthog-python-mcp`, check that it still finds the events you expect. + +### Update error handling + +Capture v1 returns a result for every event, even when the request succeeds. An event can be dropped inside a 2xx response, for example when it's over a product quota. + +8.x.x reports those events as failures. When the whole request is over the billing limit, capture returns a `402` with no per-event results instead. + +Every capture failure is a `CaptureError`, a subclass of `APIError`. It has `endpoint`, `request_id`, and `attempts`, and these fields: + +| Field | Holds | +| --- | --- | +| `status` | The HTTP status, or `0` when the request never got a response | +| `drops` | A `CaptureDroppedEvent(uuid, details)` for each event capture dropped in a 2xx response | +| `retry_exhausted` | The UUIDs still waiting for a retry after the last attempt | +| `event_results` | A `CaptureEventResult(result, details)` for each UUID that got a result in a 2xx response | +| `verdict_summary()` | Counts such as `drop/llm_events_over_quota=1, retry/not_persisted=1` | + +When `status` is `0`, `__cause__` holds the network error. In 7.x.x, `on_error` received the raw `requests` exception. + +`CaptureDroppedEvent` and `CaptureEventResult` come from `posthog.capture_send`. A `CaptureDroppedEvent` is a tuple, so `for uuid, details in error.drops` also works. An event missing from `event_results` never got a result. + +`on_error` and the SDK's log lines change with it: + +- **Every failure.** `on_error(error, batch)` receives every failure, including in `sync_mode` and from `AsyncPosthog.capture_immediate`. +- **Logs with `on_error`.** With `on_error` set, the SDK logs nothing for a failed batch. +- **Logs without `on_error`.** The SDK logs one line per failed batch, for example `2 event(s) not persisted by /i/v1/analytics/events: ...`. The line never contains event content or the server's response text. After a 2xx response it also counts the lost events by PostHog's reason, for example `drop/event_too_big=1`. +- **Removed log lines.** The 7.x.x lines `error uploading: ...`, `async capture upload failed (...)`, and `Immediate async capture failed (...)` are gone. In `sync_mode`, a failed request no longer logs the 7.x.x `Error in capture: ...` line, or the same line for another method. Update any log-based alerts that match these lines. +- **Failures in `sync_mode`.** A failed `capture()` calls `on_error` and returns `None`. With `debug=True` it calls `on_error` and then re-raises the error. +- **Retries in `sync_mode`.** The SDK retries a failed request like a background batch, in the calling thread. With the default `max_retries` of 3, a call makes up to 4 attempts. Each attempt can take up to `timeout` (`capture_ai_timeout` for AI events). 7.x.x made one attempt. +- **Blocking in `sync_mode`.** With the defaults, an analytics event whose requests keep timing out blocks the call for about a minute. +- **Captures inside `on_error`.** If a capture inside `on_error` fails, the SDK logs the failure and doesn't call `on_error` again. +- **Event content.** The SDK's own log lines no longer contain event content. The debug line for a queued event names the event and the lane. The invalid timestamp warning no longer includes the value. To inspect events, use `before_send`. +- **Hook errors.** When your `before_send` hook raises, the error line names the event and the exception type, not the exception message. The message can hold the data the hook was removing. The SDK logs the traceback at debug level. + +Retries differ from 7.x.x in four ways: + +| Behavior | 7.x.x | 8.x.x | +| --- | --- | --- | +| Statuses retried | `429` and every 5xx, but not `404` | `404`, `408`, `429`, `500`, `502`, `503`, `504`, and network errors | +| Connection tries in each attempt | Up to three | One | +| First retry wait | Up to 1 second | 100 ms | +| `Consumer` default retries | 10 | 3 | + +In 8.x.x, any other error status fails the batch at once, including the other 5xx codes. In 7.x.x, a capture request could block for up to three times the `timeout` per attempt. + +In 8.x.x the wait doubles each attempt, up to 30 seconds. Each wait varies randomly by up to 25%, so many clients don't retry at the same moment. + +A `Retry-After` header sets a minimum wait, up to 30 seconds. + +Capture itself doesn't return `429`, but a proxy in front of it can. + +### Check dropped events + +Capture rejects a whole batch when one event can't be parsed. 8.x.x drops only the invalid event, so the rest of the batch is delivered. + +| Event | 8.x.x | 7.x.x | +| --- | --- | --- | +| The name is missing, `None`, empty, or not a string | Dropped, with a warning | Sent | +| A `before_send` hook sets `distinct_id` to `None` or a non-string | Dropped, with a warning | Sent, and capture rejected the whole batch | +| The name is over 200 UTF-8 bytes | Dropped by PostHog as `event_name_too_long` | Sent, with no name limit | +| A `NaN` or infinite `float` value | Sent as `null` | Sent as `null` from 7.75.0 | +| It can't be serialized to JSON, for example with a circular reference | Dropped and logged | Logged the same line | +| A property or option key JSON can't represent, such as a tuple | Key dropped without a log | Event dropped | +| A key is an `int`, finite `float`, `bool`, or `None` | Key converted to a string | Key converted to a string | +| A key is a `NaN` or infinite `float` | Event dropped | Event dropped | + +The SDK logs one warning per reason per process for a dropped name or `distinct_id`. It doesn't convert the hook's `distinct_id` or make up an ID. + +`on_error` reports an event that PostHog drops for its name. Before 7.75.0, a `NaN` or infinite `float` value made the JSON invalid, so capture rejected the whole batch. A `NaN` value in `$set` sets that person property to `null`. A circular reference logs `Error in capture: maximum recursion depth exceeded` with a long traceback. + +Capture v1 sends `$session_id` and `$window_id` as top-level event fields, not as properties. The SDK moves them out of `properties` for you, by the value's type: + +- **A string.** The SDK sends it as given, including `""`. +- **`None`.** It counts as unset, and the SDK removes it. +- **Any other value.** The SDK removes it and doesn't send it, because capture would reject the whole batch. 7.x.x sent it as a property. The SDK logs a warning for each one, with the key and the value's type but not the value. + +8.x.x applies these size and batch rules: + +- **Analytics events.** The SDK drops and logs an analytics event over 10 MiB, because no capture request can carry it. 7.x.x dropped events over 900 KiB. +- **Capture's own limit.** Capture drops an event over its own per-event limit and reports it in `CaptureError.drops` as `event_too_big`. +- **AI events.** The SDK drops and logs an AI event over `capture_ai_max_event_bytes`. +- **Batches.** A batch stops before an event that would take it past 5 MiB. A larger event is sent alone. +- **Queues.** `flush()` and `shutdown()` drain the analytics and AI queues at the same time. + +### Check exceptions + +- **The `level=` argument.** `capture_exception` takes a `level=` argument on `Client`, `AsyncPosthog`, and the module. It sets `$exception_level`, for example `"warning"` or `"fatal"`. The default is `"error"`, and an unknown value counts as unset. +- **Reserved properties.** `capture_exception` ignores reserved exception properties in `properties`, such as `$exception_list`, `$exception_level`, and `$exception_source`. In 7.x.x they overrode the SDK's values, with a `DeprecationWarning`. Use `level=` instead of `$exception_level`. +- **Async level.** `AsyncPosthog.capture_exception` now sends `$exception_level`. +- **Async trace IDs.** `AsyncPosthog.capture_exception` now adds `$trace_id` and `$span_id` from the active OpenTelemetry span, like `Client.capture_exception`. In 7.x.x it added them only with `capture_trace_context=True`. + +### Check tracing headers + +The Django, Flask, and ASGI integrations read the `X-PostHog-Distinct-Id` and `X-PostHog-Session-Id` headers by default, as in 7.71.0 and later. The headers only fill a missing distinct ID or session ID, and any client can set them, so never use them for authentication. + +- **Turn it off.** Set `POSTHOG_MW_CAPTURE_TRACING_HEADERS = False` in Django, or pass `capture_tracing_headers=False` to the Flask or ASGI integration. +- **Upgrades from 7.68.x, 7.69.x, or 7.70.x.** If you never turned these headers on, they're now read. + +## Follow ups + +### Move to event options + +Capture v1 sends processing options in an `options` object, next to `properties`. `capture`, `capture_ai`, `set`, `set_once`, `alias`, `group_identify`, and `capture_exception` take an `options` argument: + +```python +posthog.capture("signed_up", distinct_id="user-1", options={"cookieless_mode": True}) +``` + +The MCP capture methods take `event_options` instead (see [Add MCP event options](#add-mcp-event-options)). The AI integrations take `posthog_options` (see [Send AI events with capture_ai](#send-ai-events-with-capture_ai)). + +- **Every event.** `super_options`, a new `Client`, `AsyncPosthog`, and module setting, sets options on every event, like `super_properties`. +- **One context.** `set_context_option(key, value)` sets an option for the current context, like `tag()`. `get_context_options()` returns the options of the current context. Both exist on `Client` and as module functions. +- **Async contexts.** `AsyncPosthog` has no context methods, like it has no `tag()`, so call the module functions. They apply to every client in the context. +- **Celery workers.** The Celery integration propagates context options to workers, like tags. A propagated `process_person_profile: True` turns person processing on for worker events without a distinct ID. Each of those events creates a person. +- **Celery eager mode.** In eager mode (`task_always_eager`), Celery publishes nothing, so the distinct ID, tags, and options don't reach the task's events. To carry them, pass the task's PostHog headers with `task.apply(headers=...)` or `task.apply_async(headers=...)`. +- **Methods reached.** Context tags and options reach `capture`, `capture_ai`, `capture_exception`, `alias`, and `group_identify`. Context options also reach `set` and `set_once`. `super_properties` and `super_options` reach every method. +- **Validation.** Options are sent as given. PostHog validates them. It drops an event with an option value it can't read, such as a list for `cookieless_mode`, as `invalid_options`, and `on_error` reports it. +- **Values that aren't a dict.** The SDK logs an `options` value that isn't a dict as an error and ignores it. It still sends the event. +- **Boolean options.** Pass `True` or `False` for `cookieless_mode`, `disable_skew_correction`, and `process_person_profile`. PostHog also reads common forms such as `"false"`, `"off"`, or `0`. + +Each option replaces a legacy option property: + +| Option | Replaces | +| --- | --- | +| `cookieless_mode` | `$cookieless_mode` | +| `disable_skew_correction` | `$ignore_sent_at` | +| `product_tour_id` | `$product_tour_id` | +| `process_person_profile` | `$process_person_profile` | + +Legacy option properties still work, but an option overrides its legacy property. Use options. + +These four options are the full set. PostHog ignores any other key in `options`. + +Session and window IDs stay `$session_id` and `$window_id` properties (see [Check dropped events](#check-dropped-events)). + +### Send AI events with capture_ai + +Send `$ai_` events with `capture_ai`. `capture()` sends every event to `/i/v1/analytics/events`, including `$ai_` events. + +PostHog accepts them there for now, but this is temporary. + +The AI integrations take capture options: + +- **Wrapper methods.** Every wrapper method that takes `posthog_properties` also takes `posthog_options`, for the events of that call. This covers the sync and async OpenAI, Anthropic, and Gemini wrappers, and the Claude Agent SDK `query()` and `PostHogClaudeSDKClient`. The name keeps it apart from the Claude Agent SDK's own `options`. +- **Gemini clients.** The Gemini clients take `posthog_options` as a default for every call. A call's `posthog_options` win key by key. +- **Handlers and processors.** LangChain's `CallbackHandler` and `PostHogMiddleware` take `options=` for every event. So do OpenAI Agents' `instrument()` and `PostHogTracingProcessor`, and the Claude Agent SDK's `instrument()` and `PostHogClaudeAgentProcessor`. +- **Run metadata.** LangChain also reads `posthog_options` from run metadata, like `posthog_properties`. Like properties, the handler's or processor's options win over a run's or a query's. +- **Failed runs.** The `$exception` event LangChain captures for a failed run gets the same options. +- **Precedence.** These are the event's own options, so they win over context options and `super_options`, which still fill the keys they leave unset. `before_send` can still change them. +- **Values that aren't a dict.** The SDK logs a value that isn't a dict as a warning and ignores it. The provider call still runs, and the provider never receives `posthog_options`. + +Pass `posthog_options` to a wrapper call, or `options` to a handler: + +```python +from posthog.ai.langchain import CallbackHandler +from posthog.ai.openai import OpenAI + +client = OpenAI(posthog_client=posthog_client) +client.chat.completions.create( + model="gpt-5-mini", + messages=[{"role": "user", "content": "Hello"}], + posthog_distinct_id="user-1", + posthog_options={"cookieless_mode": True}, +) + +handler = CallbackHandler( + posthog_client, distinct_id="user-1", options={"cookieless_mode": True} +) +``` + +### Add MCP event options + +MCP events take options like other events, through an `event_options` argument and an `event_options` callback. + +- **The argument.** The `PostHogMCP` capture methods and `McpAnalytics.capture`, on the handle `instrument()` returns, take an `event_options` argument. The capture methods are `capture_tool_call`, `capture_initialize`, `capture_tools_list`, `capture_missing_capability`, and `capture_feedback`. +- **What the argument sets.** It sets options on that event. For a failed tool call, it also sets them on the `$exception` event. +- **The callback.** `MCPAnalyticsOptions(event_options=...)` sets options on every event `instrument()` captures automatically, including `$exception` events. It doesn't apply to `McpAnalytics.capture`. +- **The callback's shape.** Like `event_properties`, it's a function of `(request, extra)` that returns a dict or `None`, and it can be sync or async. +- **The core `capture`.** `PostHogMCP.capture()` is the core client's `capture`, so it takes `options`. The MCP capture methods take `event_options`. +- **Precedence.** The SDK passes these options as the event's own options, so they win over context options and `super_options`. +- **Events without an identity.** An event without an identity always sends `process_person_profile: False`, even when `event_options` sets it to `True`. Its distinct ID is the session ID, so person processing would create a person for each session. To process a person, identify the user with `identify` or pass `distinct_id`. +- **Values that aren't a dict.** The SDK logs an `event_options` value that isn't a dict and ignores it. It still sends the event. + +Set the callback in `instrument()`, or pass the argument to a capture method: + +```python +from posthog.mcp import MCPAnalyticsOptions, PostHogMCP, instrument + +instrument( + server, + posthog, + MCPAnalyticsOptions(event_options=lambda request, extra: {"cookieless_mode": True}), +) + +mcp_client = PostHogMCP("phc_...") +mcp_client.capture_tool_call( + "search_docs", + distinct_id="user-1", + event_options={"process_person_profile": False}, +) +``` + +`instrument()` captures `$mcp_tool_call` after the tool handler returns. A context you open inside the handler has ended by then, so options you set in it with `set_context_option` don't reach `$mcp_tool_call`. + +Events you capture inside that context still get them. To set options on `$mcp_tool_call`, use the `event_options` callback. + +### Rename deprecated settings + +These old names still work or have no effect in 8.x.x: + +| Old | New | +| --- | --- | +| `trust_tracing_headers`, `POSTHOG_MW_TRUST_TRACING_HEADERS` | `capture_tracing_headers`, `POSTHOG_MW_CAPTURE_TRACING_HEADERS` | +| `_use_ai_lane`, `_enable_multimodal_capture` | `enable_full_ai_capture` | +| `posthog.capture_mode` | Nothing | +| A `gzip=` keyword on `request.post` or `request.flags` | Nothing | + +The 7.68.x tracing header names still work, but are deprecated. `_use_ai_lane` and `_enable_multimodal_capture` still work as aliases. + +Setting `posthog.capture_mode` on the module has no effect. A `gzip=` keyword raises no error, and it's sent as a field in the request body. diff --git a/examples/example-ai-crewai/pyproject.toml b/examples/example-ai-crewai/pyproject.toml index f4872d20a..694257691 100644 --- a/examples/example-ai-crewai/pyproject.toml +++ b/examples/example-ai-crewai/pyproject.toml @@ -3,7 +3,10 @@ name = "example-ai-crewai" version = "0.1.0" requires-python = ">=3.10" dependencies = [ - "posthog==7.9.12", + "posthog", "crewai>=0.80.0", "litellm>=1.100.4", ] + +[tool.uv.sources] +posthog = { path = "../.." } diff --git a/examples/example-ai-crewai/uv.lock b/examples/example-ai-crewai/uv.lock index 6ec99c2ae..0a0950f30 100644 --- a/examples/example-ai-crewai/uv.lock +++ b/examples/example-ai-crewai/uv.lock @@ -306,15 +306,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/3e/83/65ecd7449fbdc5b91de15e6a9fcb4766076da8c4b117d3eb1194582e4de4/auth0_python-5.3.0-py3-none-any.whl", hash = "sha256:251fb2f524f7bc4f88b69e48b0444d05f71769aef4f61076f2ba3573ca69dae6", size = 2038474, upload-time = "2026-04-09T13:27:03.808Z" }, ] -[[package]] -name = "backoff" -version = "2.2.1" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/47/d7/5bbeb12c44d7c4f2fb5b56abce497eb5ed9f34d85701de869acedd602619/backoff-2.2.1.tar.gz", hash = "sha256:03f829f5bb1923180821643f8753b0502c3b682293992485b0eef2807afa5cba", size = 17001, upload-time = "2022-10-05T19:19:32.061Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/df/73/b6e24bd22e6720ca8ee9a85a0c4a2971af8497d8f3193fa05390cbd46e09/backoff-2.2.1-py3-none-any.whl", hash = "sha256:63579f9a0628e06278f7e47b7d7d5b6ce20dc65c5e96a6f3ca99a6adca0396e8", size = 15148, upload-time = "2022-10-05T19:19:30.546Z" }, -] - [[package]] name = "bcrypt" version = "5.0.0" @@ -869,7 +860,7 @@ dependencies = [ requires-dist = [ { name = "crewai", specifier = ">=0.80.0" }, { name = "litellm", specifier = ">=1.100.4" }, - { name = "posthog", specifier = "==7.9.12" }, + { name = "posthog", directory = "../../" }, ] [[package]] @@ -2744,20 +2735,96 @@ wheels = [ [[package]] name = "posthog" -version = "7.9.12" -source = { registry = "https://pypi.org/simple" } +version = "7.86.6" +source = { directory = "../../" } dependencies = [ - { name = "backoff" }, { name = "distro" }, - { name = "python-dateutil" }, { name = "requests" }, - { name = "six" }, { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/1c/a7/2865487853061fbd62383492237b546d2d8f7c1846272350d2b9e14138cd/posthog-7.9.12.tar.gz", hash = "sha256:ebabf2eb2e1c1fbf22b0759df4644623fa43cc6c9dcbe9fd429b7937d14251ec", size = 176828, upload-time = "2026-03-12T09:01:15.184Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/65/a9/7a803aed5a5649cf78ea7b31e90d0080181ba21f739243e1741a1e607f1f/posthog-7.9.12-py3-none-any.whl", hash = "sha256:7175bd1698a566bfea98a016c64e3456399f8046aeeca8f1d04ae5bf6c5a38d0", size = 202469, upload-time = "2026-03-12T09:01:13.38Z" }, -] + +[package.metadata] +requires-dist = [ + { name = "anthropic", marker = "extra == 'test'", specifier = ">=0.72" }, + { name = "celery", marker = "extra == 'test'", specifier = ">=5.3,<6" }, + { name = "claude-agent-sdk", marker = "extra == 'test'" }, + { name = "coverage", marker = "extra == 'test'" }, + { name = "distro", specifier = ">=1.5.0" }, + { name = "django", marker = "extra == 'test'", specifier = ">=5.2.15,<6.0" }, + { name = "django-stubs", marker = "extra == 'dev'" }, + { name = "djangorestframework", marker = "extra == 'test'", specifier = ">=3.15,<4" }, + { name = "fastapi", marker = "extra == 'test'", specifier = ">=0.115,<1" }, + { name = "fastmcp", marker = "extra == 'test'", specifier = ">=2.0" }, + { name = "flask", marker = "extra == 'test'", specifier = ">=2.2" }, + { name = "freezegun", marker = "extra == 'test'", specifier = "==1.5.1" }, + { name = "gevent", marker = "implementation_name == 'cpython' and extra == 'test'", specifier = ">=25.4.1" }, + { name = "google-genai", marker = "extra == 'test'" }, + { name = "griffe", marker = "extra == 'dev'" }, + { name = "griffe", marker = "extra == 'test'" }, + { name = "griffe2md", marker = "extra == 'dev'" }, + { name = "griffe2md", marker = "extra == 'test'" }, + { name = "httpx", marker = "extra == 'async'", specifier = ">=0.27.0,<1.0" }, + { name = "jsonschema", marker = "extra == 'test'", specifier = ">=4.0" }, + { name = "langchain", marker = "extra == 'langchain'", specifier = ">=1.3.9" }, + { name = "langchain", marker = "extra == 'test'", specifier = ">=1.3.9" }, + { name = "langchain-anthropic", marker = "extra == 'test'", specifier = ">=1.0" }, + { name = "langchain-community", marker = "extra == 'test'", specifier = ">=0.4" }, + { name = "langchain-core", marker = "extra == 'test'", specifier = ">=1.0" }, + { name = "langchain-openai", marker = "extra == 'test'", specifier = ">=1.1.14" }, + { name = "langgraph", marker = "extra == 'test'", specifier = ">=1.0" }, + { name = "langgraph-checkpoint", marker = "extra == 'test'", specifier = ">=4.1.1" }, + { name = "lxml", marker = "extra == 'dev'" }, + { name = "mcp", marker = "extra == 'test'", specifier = ">=1.28.1,<2" }, + { name = "mypy", marker = "extra == 'dev'" }, + { name = "mypy-baseline", marker = "extra == 'dev'" }, + { name = "openai-agents", marker = "extra == 'test'", specifier = ">=0.18" }, + { name = "opentelemetry-exporter-otlp-proto-http", marker = "extra == 'metrics'", specifier = ">=1.39.0" }, + { name = "opentelemetry-exporter-otlp-proto-http", marker = "extra == 'otel'", specifier = ">=1.20.0" }, + { name = "opentelemetry-exporter-otlp-proto-http", marker = "extra == 'test'", specifier = ">=1.20.0" }, + { name = "opentelemetry-instrumentation", marker = "extra == 'metrics'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-aiohttp-client", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-celery", marker = "extra == 'test'", specifier = ">=0.41b0" }, + { name = "opentelemetry-instrumentation-django", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-flask", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-httpx", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-requests", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-sqlite3", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-system-metrics", marker = "extra == 'metrics'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-system-metrics", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-wsgi", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-sdk", marker = "extra == 'metrics'", specifier = ">=1.39.0" }, + { name = "opentelemetry-sdk", marker = "extra == 'otel'", specifier = ">=1.20.0" }, + { name = "opentelemetry-sdk", marker = "extra == 'test'", specifier = ">=1.20.0" }, + { name = "packaging", marker = "extra == 'dev'" }, + { name = "parameterized", marker = "extra == 'test'", specifier = ">=0.8.1" }, + { name = "pre-commit", marker = "extra == 'dev'" }, + { name = "pydantic", marker = "extra == 'dev'", specifier = ">=2.12.0" }, + { name = "pydantic", marker = "extra == 'test'", specifier = ">=2.12.0" }, + { name = "pytest", marker = "extra == 'test'" }, + { name = "pytest-asyncio", marker = "extra == 'test'" }, + { name = "pytest-bdd", marker = "extra == 'test'", specifier = ">=8.1.0" }, + { name = "pytest-timeout", marker = "extra == 'test'" }, + { name = "python-dateutil", marker = "extra == 'test'", specifier = ">=2.9.0.post0" }, + { name = "requests", specifier = ">=2.7,<3.0" }, + { name = "ruff", marker = "extra == 'dev'" }, + { name = "setuptools", marker = "extra == 'dev'" }, + { name = "tiktoken", marker = "extra == 'test'", specifier = ">=0.12.0" }, + { name = "tomli", marker = "extra == 'dev'" }, + { name = "tomli-w", marker = "extra == 'dev'" }, + { name = "twine", marker = "extra == 'dev'" }, + { name = "types-requests", marker = "extra == 'dev'" }, + { name = "types-setuptools", marker = "extra == 'dev'" }, + { name = "typing-extensions", specifier = ">=4.2.0" }, + { name = "tzdata", marker = "extra == 'test'" }, + { name = "wheel", marker = "extra == 'dev'" }, + { name = "zstandard", marker = "extra == 'test'", specifier = ">=0.23.0" }, + { name = "zstandard", marker = "extra == 'zstd'", specifier = ">=0.23.0" }, +] +provides-extras = ["langchain", "async", "zstd", "otel", "metrics", "dev", "test"] + +[package.metadata.requires-dev] +dev = [{ name = "claude-agent-sdk", specifier = ">=0.1.50" }] [[package]] name = "prompt-toolkit" diff --git a/examples/example-ai-dspy/pyproject.toml b/examples/example-ai-dspy/pyproject.toml index 47c1ce9fd..c4dbff5b7 100644 --- a/examples/example-ai-dspy/pyproject.toml +++ b/examples/example-ai-dspy/pyproject.toml @@ -3,7 +3,10 @@ name = "example-ai-dspy" version = "0.1.0" requires-python = ">=3.10" dependencies = [ - "posthog==7.9.12", + "posthog", "dspy>=2.5.0", "litellm==1.100.4", ] + +[tool.uv.sources] +posthog = { path = "../.." } diff --git a/examples/example-ai-dspy/uv.lock b/examples/example-ai-dspy/uv.lock index d97600016..3e43adc7d 100644 --- a/examples/example-ai-dspy/uv.lock +++ b/examples/example-ai-dspy/uv.lock @@ -291,15 +291,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/64/b4/17d4b0b2a2dc85a6df63d1157e028ed19f90d4cd97c36717afef2bc2f395/attrs-26.1.0-py3-none-any.whl", hash = "sha256:c647aa4a12dfbad9333ca4e71fe62ddc36f4e63b2d260a37a8b83d2f043ac309", size = 67548, upload-time = "2026-03-19T14:22:23.645Z" }, ] -[[package]] -name = "backoff" -version = "2.2.1" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/47/d7/5bbeb12c44d7c4f2fb5b56abce497eb5ed9f34d85701de869acedd602619/backoff-2.2.1.tar.gz", hash = "sha256:03f829f5bb1923180821643f8753b0502c3b682293992485b0eef2807afa5cba", size = 17001, upload-time = "2022-10-05T19:19:32.061Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/df/73/b6e24bd22e6720ca8ee9a85a0c4a2971af8497d8f3193fa05390cbd46e09/backoff-2.2.1-py3-none-any.whl", hash = "sha256:63579f9a0628e06278f7e47b7d7d5b6ce20dc65c5e96a6f3ca99a6adca0396e8", size = 15148, upload-time = "2022-10-05T19:19:30.546Z" }, -] - [[package]] name = "boto3" version = "1.43.123" @@ -555,7 +546,7 @@ dependencies = [ requires-dist = [ { name = "dspy", specifier = ">=2.5.0" }, { name = "litellm", specifier = "==1.100.4" }, - { name = "posthog", specifier = "==7.9.12" }, + { name = "posthog", directory = "../../" }, ] [[package]] @@ -1707,20 +1698,96 @@ wheels = [ [[package]] name = "posthog" -version = "7.9.12" -source = { registry = "https://pypi.org/simple" } +version = "7.86.6" +source = { directory = "../../" } dependencies = [ - { name = "backoff" }, { name = "distro" }, - { name = "python-dateutil" }, { name = "requests" }, - { name = "six" }, { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/1c/a7/2865487853061fbd62383492237b546d2d8f7c1846272350d2b9e14138cd/posthog-7.9.12.tar.gz", hash = "sha256:ebabf2eb2e1c1fbf22b0759df4644623fa43cc6c9dcbe9fd429b7937d14251ec", size = 176828, upload-time = "2026-03-12T09:01:15.184Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/65/a9/7a803aed5a5649cf78ea7b31e90d0080181ba21f739243e1741a1e607f1f/posthog-7.9.12-py3-none-any.whl", hash = "sha256:7175bd1698a566bfea98a016c64e3456399f8046aeeca8f1d04ae5bf6c5a38d0", size = 202469, upload-time = "2026-03-12T09:01:13.38Z" }, -] + +[package.metadata] +requires-dist = [ + { name = "anthropic", marker = "extra == 'test'", specifier = ">=0.72" }, + { name = "celery", marker = "extra == 'test'", specifier = ">=5.3,<6" }, + { name = "claude-agent-sdk", marker = "extra == 'test'" }, + { name = "coverage", marker = "extra == 'test'" }, + { name = "distro", specifier = ">=1.5.0" }, + { name = "django", marker = "extra == 'test'", specifier = ">=5.2.15,<6.0" }, + { name = "django-stubs", marker = "extra == 'dev'" }, + { name = "djangorestframework", marker = "extra == 'test'", specifier = ">=3.15,<4" }, + { name = "fastapi", marker = "extra == 'test'", specifier = ">=0.115,<1" }, + { name = "fastmcp", marker = "extra == 'test'", specifier = ">=2.0" }, + { name = "flask", marker = "extra == 'test'", specifier = ">=2.2" }, + { name = "freezegun", marker = "extra == 'test'", specifier = "==1.5.1" }, + { name = "gevent", marker = "implementation_name == 'cpython' and extra == 'test'", specifier = ">=25.4.1" }, + { name = "google-genai", marker = "extra == 'test'" }, + { name = "griffe", marker = "extra == 'dev'" }, + { name = "griffe", marker = "extra == 'test'" }, + { name = "griffe2md", marker = "extra == 'dev'" }, + { name = "griffe2md", marker = "extra == 'test'" }, + { name = "httpx", marker = "extra == 'async'", specifier = ">=0.27.0,<1.0" }, + { name = "jsonschema", marker = "extra == 'test'", specifier = ">=4.0" }, + { name = "langchain", marker = "extra == 'langchain'", specifier = ">=1.3.9" }, + { name = "langchain", marker = "extra == 'test'", specifier = ">=1.3.9" }, + { name = "langchain-anthropic", marker = "extra == 'test'", specifier = ">=1.0" }, + { name = "langchain-community", marker = "extra == 'test'", specifier = ">=0.4" }, + { name = "langchain-core", marker = "extra == 'test'", specifier = ">=1.0" }, + { name = "langchain-openai", marker = "extra == 'test'", specifier = ">=1.1.14" }, + { name = "langgraph", marker = "extra == 'test'", specifier = ">=1.0" }, + { name = "langgraph-checkpoint", marker = "extra == 'test'", specifier = ">=4.1.1" }, + { name = "lxml", marker = "extra == 'dev'" }, + { name = "mcp", marker = "extra == 'test'", specifier = ">=1.28.1,<2" }, + { name = "mypy", marker = "extra == 'dev'" }, + { name = "mypy-baseline", marker = "extra == 'dev'" }, + { name = "openai-agents", marker = "extra == 'test'", specifier = ">=0.18" }, + { name = "opentelemetry-exporter-otlp-proto-http", marker = "extra == 'metrics'", specifier = ">=1.39.0" }, + { name = "opentelemetry-exporter-otlp-proto-http", marker = "extra == 'otel'", specifier = ">=1.20.0" }, + { name = "opentelemetry-exporter-otlp-proto-http", marker = "extra == 'test'", specifier = ">=1.20.0" }, + { name = "opentelemetry-instrumentation", marker = "extra == 'metrics'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-aiohttp-client", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-celery", marker = "extra == 'test'", specifier = ">=0.41b0" }, + { name = "opentelemetry-instrumentation-django", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-flask", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-httpx", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-requests", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-sqlite3", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-system-metrics", marker = "extra == 'metrics'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-system-metrics", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-wsgi", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-sdk", marker = "extra == 'metrics'", specifier = ">=1.39.0" }, + { name = "opentelemetry-sdk", marker = "extra == 'otel'", specifier = ">=1.20.0" }, + { name = "opentelemetry-sdk", marker = "extra == 'test'", specifier = ">=1.20.0" }, + { name = "packaging", marker = "extra == 'dev'" }, + { name = "parameterized", marker = "extra == 'test'", specifier = ">=0.8.1" }, + { name = "pre-commit", marker = "extra == 'dev'" }, + { name = "pydantic", marker = "extra == 'dev'", specifier = ">=2.12.0" }, + { name = "pydantic", marker = "extra == 'test'", specifier = ">=2.12.0" }, + { name = "pytest", marker = "extra == 'test'" }, + { name = "pytest-asyncio", marker = "extra == 'test'" }, + { name = "pytest-bdd", marker = "extra == 'test'", specifier = ">=8.1.0" }, + { name = "pytest-timeout", marker = "extra == 'test'" }, + { name = "python-dateutil", marker = "extra == 'test'", specifier = ">=2.9.0.post0" }, + { name = "requests", specifier = ">=2.7,<3.0" }, + { name = "ruff", marker = "extra == 'dev'" }, + { name = "setuptools", marker = "extra == 'dev'" }, + { name = "tiktoken", marker = "extra == 'test'", specifier = ">=0.12.0" }, + { name = "tomli", marker = "extra == 'dev'" }, + { name = "tomli-w", marker = "extra == 'dev'" }, + { name = "twine", marker = "extra == 'dev'" }, + { name = "types-requests", marker = "extra == 'dev'" }, + { name = "types-setuptools", marker = "extra == 'dev'" }, + { name = "typing-extensions", specifier = ">=4.2.0" }, + { name = "tzdata", marker = "extra == 'test'" }, + { name = "wheel", marker = "extra == 'dev'" }, + { name = "zstandard", marker = "extra == 'test'", specifier = ">=0.23.0" }, + { name = "zstandard", marker = "extra == 'zstd'", specifier = ">=0.23.0" }, +] +provides-extras = ["langchain", "async", "zstd", "otel", "metrics", "dev", "test"] + +[package.metadata.requires-dev] +dev = [{ name = "claude-agent-sdk", specifier = ">=0.1.50" }] [[package]] name = "propcache" diff --git a/examples/example-ai-litellm/pyproject.toml b/examples/example-ai-litellm/pyproject.toml index 5efd3520a..aaa2879c8 100644 --- a/examples/example-ai-litellm/pyproject.toml +++ b/examples/example-ai-litellm/pyproject.toml @@ -3,6 +3,9 @@ name = "example-ai-litellm" version = "0.1.0" requires-python = ">=3.10" dependencies = [ - "posthog==7.9.12", + "posthog", "litellm==1.100.4", ] + +[tool.uv.sources] +posthog = { path = "../.." } diff --git a/examples/example-ai-litellm/uv.lock b/examples/example-ai-litellm/uv.lock index e8f2a90d6..dd170f784 100644 --- a/examples/example-ai-litellm/uv.lock +++ b/examples/example-ai-litellm/uv.lock @@ -264,15 +264,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/64/b4/17d4b0b2a2dc85a6df63d1157e028ed19f90d4cd97c36717afef2bc2f395/attrs-26.1.0-py3-none-any.whl", hash = "sha256:c647aa4a12dfbad9333ca4e71fe62ddc36f4e63b2d260a37a8b83d2f043ac309", size = 67548, upload-time = "2026-03-19T14:22:23.645Z" }, ] -[[package]] -name = "backoff" -version = "2.2.1" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/47/d7/5bbeb12c44d7c4f2fb5b56abce497eb5ed9f34d85701de869acedd602619/backoff-2.2.1.tar.gz", hash = "sha256:03f829f5bb1923180821643f8753b0502c3b682293992485b0eef2807afa5cba", size = 17001, upload-time = "2022-10-05T19:19:32.061Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/df/73/b6e24bd22e6720ca8ee9a85a0c4a2971af8497d8f3193fa05390cbd46e09/backoff-2.2.1-py3-none-any.whl", hash = "sha256:63579f9a0628e06278f7e47b7d7d5b6ce20dc65c5e96a6f3ca99a6adca0396e8", size = 15148, upload-time = "2022-10-05T19:19:30.546Z" }, -] - [[package]] name = "boto3" version = "1.43.123" @@ -457,7 +448,7 @@ dependencies = [ [package.metadata] requires-dist = [ { name = "litellm", specifier = "==1.100.4" }, - { name = "posthog", specifier = "==7.9.12" }, + { name = "posthog", directory = "../../" }, ] [[package]] @@ -1278,20 +1269,96 @@ wheels = [ [[package]] name = "posthog" -version = "7.9.12" -source = { registry = "https://pypi.org/simple" } +version = "7.86.6" +source = { directory = "../../" } dependencies = [ - { name = "backoff" }, { name = "distro" }, - { name = "python-dateutil" }, { name = "requests" }, - { name = "six" }, { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/1c/a7/2865487853061fbd62383492237b546d2d8f7c1846272350d2b9e14138cd/posthog-7.9.12.tar.gz", hash = "sha256:ebabf2eb2e1c1fbf22b0759df4644623fa43cc6c9dcbe9fd429b7937d14251ec", size = 176828, upload-time = "2026-03-12T09:01:15.184Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/65/a9/7a803aed5a5649cf78ea7b31e90d0080181ba21f739243e1741a1e607f1f/posthog-7.9.12-py3-none-any.whl", hash = "sha256:7175bd1698a566bfea98a016c64e3456399f8046aeeca8f1d04ae5bf6c5a38d0", size = 202469, upload-time = "2026-03-12T09:01:13.38Z" }, -] + +[package.metadata] +requires-dist = [ + { name = "anthropic", marker = "extra == 'test'", specifier = ">=0.72" }, + { name = "celery", marker = "extra == 'test'", specifier = ">=5.3,<6" }, + { name = "claude-agent-sdk", marker = "extra == 'test'" }, + { name = "coverage", marker = "extra == 'test'" }, + { name = "distro", specifier = ">=1.5.0" }, + { name = "django", marker = "extra == 'test'", specifier = ">=5.2.15,<6.0" }, + { name = "django-stubs", marker = "extra == 'dev'" }, + { name = "djangorestframework", marker = "extra == 'test'", specifier = ">=3.15,<4" }, + { name = "fastapi", marker = "extra == 'test'", specifier = ">=0.115,<1" }, + { name = "fastmcp", marker = "extra == 'test'", specifier = ">=2.0" }, + { name = "flask", marker = "extra == 'test'", specifier = ">=2.2" }, + { name = "freezegun", marker = "extra == 'test'", specifier = "==1.5.1" }, + { name = "gevent", marker = "implementation_name == 'cpython' and extra == 'test'", specifier = ">=25.4.1" }, + { name = "google-genai", marker = "extra == 'test'" }, + { name = "griffe", marker = "extra == 'dev'" }, + { name = "griffe", marker = "extra == 'test'" }, + { name = "griffe2md", marker = "extra == 'dev'" }, + { name = "griffe2md", marker = "extra == 'test'" }, + { name = "httpx", marker = "extra == 'async'", specifier = ">=0.27.0,<1.0" }, + { name = "jsonschema", marker = "extra == 'test'", specifier = ">=4.0" }, + { name = "langchain", marker = "extra == 'langchain'", specifier = ">=1.3.9" }, + { name = "langchain", marker = "extra == 'test'", specifier = ">=1.3.9" }, + { name = "langchain-anthropic", marker = "extra == 'test'", specifier = ">=1.0" }, + { name = "langchain-community", marker = "extra == 'test'", specifier = ">=0.4" }, + { name = "langchain-core", marker = "extra == 'test'", specifier = ">=1.0" }, + { name = "langchain-openai", marker = "extra == 'test'", specifier = ">=1.1.14" }, + { name = "langgraph", marker = "extra == 'test'", specifier = ">=1.0" }, + { name = "langgraph-checkpoint", marker = "extra == 'test'", specifier = ">=4.1.1" }, + { name = "lxml", marker = "extra == 'dev'" }, + { name = "mcp", marker = "extra == 'test'", specifier = ">=1.28.1,<2" }, + { name = "mypy", marker = "extra == 'dev'" }, + { name = "mypy-baseline", marker = "extra == 'dev'" }, + { name = "openai-agents", marker = "extra == 'test'", specifier = ">=0.18" }, + { name = "opentelemetry-exporter-otlp-proto-http", marker = "extra == 'metrics'", specifier = ">=1.39.0" }, + { name = "opentelemetry-exporter-otlp-proto-http", marker = "extra == 'otel'", specifier = ">=1.20.0" }, + { name = "opentelemetry-exporter-otlp-proto-http", marker = "extra == 'test'", specifier = ">=1.20.0" }, + { name = "opentelemetry-instrumentation", marker = "extra == 'metrics'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-aiohttp-client", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-celery", marker = "extra == 'test'", specifier = ">=0.41b0" }, + { name = "opentelemetry-instrumentation-django", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-flask", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-httpx", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-requests", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-sqlite3", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-system-metrics", marker = "extra == 'metrics'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-system-metrics", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-instrumentation-wsgi", marker = "extra == 'test'", specifier = ">=0.60b0" }, + { name = "opentelemetry-sdk", marker = "extra == 'metrics'", specifier = ">=1.39.0" }, + { name = "opentelemetry-sdk", marker = "extra == 'otel'", specifier = ">=1.20.0" }, + { name = "opentelemetry-sdk", marker = "extra == 'test'", specifier = ">=1.20.0" }, + { name = "packaging", marker = "extra == 'dev'" }, + { name = "parameterized", marker = "extra == 'test'", specifier = ">=0.8.1" }, + { name = "pre-commit", marker = "extra == 'dev'" }, + { name = "pydantic", marker = "extra == 'dev'", specifier = ">=2.12.0" }, + { name = "pydantic", marker = "extra == 'test'", specifier = ">=2.12.0" }, + { name = "pytest", marker = "extra == 'test'" }, + { name = "pytest-asyncio", marker = "extra == 'test'" }, + { name = "pytest-bdd", marker = "extra == 'test'", specifier = ">=8.1.0" }, + { name = "pytest-timeout", marker = "extra == 'test'" }, + { name = "python-dateutil", marker = "extra == 'test'", specifier = ">=2.9.0.post0" }, + { name = "requests", specifier = ">=2.7,<3.0" }, + { name = "ruff", marker = "extra == 'dev'" }, + { name = "setuptools", marker = "extra == 'dev'" }, + { name = "tiktoken", marker = "extra == 'test'", specifier = ">=0.12.0" }, + { name = "tomli", marker = "extra == 'dev'" }, + { name = "tomli-w", marker = "extra == 'dev'" }, + { name = "twine", marker = "extra == 'dev'" }, + { name = "types-requests", marker = "extra == 'dev'" }, + { name = "types-setuptools", marker = "extra == 'dev'" }, + { name = "typing-extensions", specifier = ">=4.2.0" }, + { name = "tzdata", marker = "extra == 'test'" }, + { name = "wheel", marker = "extra == 'dev'" }, + { name = "zstandard", marker = "extra == 'test'", specifier = ">=0.23.0" }, + { name = "zstandard", marker = "extra == 'zstd'", specifier = ">=0.23.0" }, +] +provides-extras = ["langchain", "async", "zstd", "otel", "metrics", "dev", "test"] + +[package.metadata.requires-dev] +dev = [{ name = "claude-agent-sdk", specifier = ">=0.1.50" }] [[package]] name = "propcache" diff --git a/examples/example-ai-openai-agents/pyproject.toml b/examples/example-ai-openai-agents/pyproject.toml index 647400643..06ad91cd7 100644 --- a/examples/example-ai-openai-agents/pyproject.toml +++ b/examples/example-ai-openai-agents/pyproject.toml @@ -3,6 +3,9 @@ name = "example-ai-openai-agents" version = "0.1.0" requires-python = ">=3.10" dependencies = [ - "posthog==7.9.12", + "posthog", "openai-agents==0.13.1", ] + +[tool.uv.sources] +posthog = { path = "../.." } diff --git a/examples/example-ai-openai-agents/uv.lock b/examples/example-ai-openai-agents/uv.lock index 2534f5151..fcf3831a8 100644 --- a/examples/example-ai-openai-agents/uv.lock +++ b/examples/example-ai-openai-agents/uv.lock @@ -9,7 +9,7 @@ resolution-markers = [ ] [options] -exclude-newer = "0001-01-01T00:00:00Z" # This has no effect and is included for backwards compatibility when using relative exclude-newer values. +exclude-newer = "2026-10-03T03:16:09.242998Z" exclude-newer-span = "P7D" [options.exclude-newer-package] @@ -47,15 +47,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/64/b4/17d4b0b2a2dc85a6df63d1157e028ed19f90d4cd97c36717afef2bc2f395/attrs-26.1.0-py3-none-any.whl", hash = "sha256:c647aa4a12dfbad9333ca4e71fe62ddc36f4e63b2d260a37a8b83d2f043ac309", size = 67548, upload-time = "2026-03-19T14:22:23.645Z" }, ] -[[package]] -name = "backoff" -version = "2.2.1" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/47/d7/5bbeb12c44d7c4f2fb5b56abce497eb5ed9f34d85701de869acedd602619/backoff-2.2.1.tar.gz", hash = "sha256:03f829f5bb1923180821643f8753b0502c3b682293992485b0eef2807afa5cba", size = 17001, upload-time = "2022-10-05T19:19:32.061Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/df/73/b6e24bd22e6720ca8ee9a85a0c4a2971af8497d8f3193fa05390cbd46e09/backoff-2.2.1-py3-none-any.whl", hash = "sha256:63579f9a0628e06278f7e47b7d7d5b6ce20dc65c5e96a6f3ca99a6adca0396e8", size = 15148, upload-time = "2022-10-05T19:19:30.546Z" }, -] - [[package]] name = "certifi" version = "2026.10.23" @@ -379,7 +370,7 @@ dependencies = [ [package.metadata] requires-dist = [ { name = "openai-agents", specifier = "==0.13.1" }, - { name = "posthog", specifier = "==7.9.12" }, + { name = "posthog", directory = "../../" }, ] [[package]] @@ -387,7 +378,7 @@ name = "exceptiongroup" version = "1.3.1" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "typing-extensions" }, + { name = "typing-extensions", marker = "python_full_version < '3.13'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" } wheels = [ @@ -649,20 +640,75 @@ wheels = [ [[package]] name = "posthog" -version = "7.9.12" -source = { registry = "https://pypi.org/simple" } +version = "7.64.1" +source = { directory = "../../" } dependencies = [ - { name = "backoff" }, { name = "distro" }, - { name = "python-dateutil" }, { name = "requests" }, - { name = "six" }, { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/1c/a7/2865487853061fbd62383492237b546d2d8f7c1846272350d2b9e14138cd/posthog-7.9.12.tar.gz", hash = "sha256:ebabf2eb2e1c1fbf22b0759df4644623fa43cc6c9dcbe9fd429b7937d14251ec", size = 176828, upload-time = "2026-03-12T09:01:15.184Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/65/a9/7a803aed5a5649cf78ea7b31e90d0080181ba21f739243e1741a1e607f1f/posthog-7.9.12-py3-none-any.whl", hash = "sha256:7175bd1698a566bfea98a016c64e3456399f8046aeeca8f1d04ae5bf6c5a38d0", size = 202469, upload-time = "2026-03-12T09:01:13.38Z" }, -] + +[package.metadata] +requires-dist = [ + { name = "anthropic", marker = "extra == 'test'", specifier = ">=0.72" }, + { name = "claude-agent-sdk", marker = "extra == 'test'" }, + { name = "coverage", marker = "extra == 'test'" }, + { name = "distro", specifier = ">=1.5.0" }, + { name = "django", marker = "extra == 'test'", specifier = ">=5.2.15,<6.0" }, + { name = "django-stubs", marker = "extra == 'dev'" }, + { name = "fastmcp", marker = "extra == 'test'", specifier = ">=2.0" }, + { name = "freezegun", marker = "extra == 'test'", specifier = "==1.5.1" }, + { name = "gevent", marker = "implementation_name == 'cpython' and extra == 'test'", specifier = ">=25.4.1" }, + { name = "google-genai", marker = "extra == 'test'" }, + { name = "griffe", marker = "extra == 'dev'" }, + { name = "httpx", marker = "extra == 'async'", specifier = ">=0.27.0,<1.0" }, + { name = "jsonschema", marker = "extra == 'test'", specifier = ">=4.0" }, + { name = "langchain", marker = "extra == 'langchain'", specifier = ">=1.3.9" }, + { name = "langchain", marker = "extra == 'test'", specifier = ">=1.3.9" }, + { name = "langchain-anthropic", marker = "extra == 'test'", specifier = ">=1.0" }, + { name = "langchain-community", marker = "extra == 'test'", specifier = ">=0.4" }, + { name = "langchain-core", marker = "extra == 'test'", specifier = ">=1.0" }, + { name = "langchain-openai", marker = "extra == 'test'", specifier = ">=1.1.14" }, + { name = "langgraph", marker = "extra == 'test'", specifier = ">=1.0" }, + { name = "langgraph-checkpoint", marker = "extra == 'test'", specifier = ">=4.1.1" }, + { name = "lxml", marker = "extra == 'dev'" }, + { name = "mcp", marker = "extra == 'test'", specifier = ">=1.28.1,<2" }, + { name = "mypy", marker = "extra == 'dev'" }, + { name = "mypy-baseline", marker = "extra == 'dev'" }, + { name = "openai-agents", marker = "extra == 'test'", specifier = ">=0.18" }, + { name = "opentelemetry-exporter-otlp-proto-http", marker = "extra == 'otel'", specifier = ">=1.20.0" }, + { name = "opentelemetry-exporter-otlp-proto-http", marker = "extra == 'test'", specifier = ">=1.20.0" }, + { name = "opentelemetry-sdk", marker = "extra == 'otel'", specifier = ">=1.20.0" }, + { name = "opentelemetry-sdk", marker = "extra == 'test'", specifier = ">=1.20.0" }, + { name = "packaging", marker = "extra == 'dev'" }, + { name = "parameterized", marker = "extra == 'test'", specifier = ">=0.8.1" }, + { name = "pre-commit", marker = "extra == 'dev'" }, + { name = "pydantic", marker = "extra == 'dev'", specifier = ">=2.12.0" }, + { name = "pydantic", marker = "extra == 'test'", specifier = ">=2.12.0" }, + { name = "pytest", marker = "extra == 'test'" }, + { name = "pytest-asyncio", marker = "extra == 'test'" }, + { name = "pytest-bdd", marker = "extra == 'test'", specifier = ">=8.1.0" }, + { name = "pytest-timeout", marker = "extra == 'test'" }, + { name = "python-dateutil", marker = "extra == 'test'", specifier = ">=2.9.0.post0" }, + { name = "requests", specifier = ">=2.7,<3.0" }, + { name = "ruff", marker = "extra == 'dev'" }, + { name = "setuptools", marker = "extra == 'dev'" }, + { name = "tiktoken", marker = "extra == 'test'", specifier = ">=0.12.0" }, + { name = "tomli", marker = "extra == 'dev'" }, + { name = "tomli-w", marker = "extra == 'dev'" }, + { name = "twine", marker = "extra == 'dev'" }, + { name = "types-requests", marker = "extra == 'dev'" }, + { name = "types-setuptools", marker = "extra == 'dev'" }, + { name = "typing-extensions", specifier = ">=4.2.0" }, + { name = "tzdata", marker = "extra == 'test'" }, + { name = "wheel", marker = "extra == 'dev'" }, + { name = "zstandard", marker = "extra == 'test'", specifier = ">=0.23.0" }, + { name = "zstandard", marker = "extra == 'zstd'", specifier = ">=0.23.0" }, +] +provides-extras = ["langchain", "async", "zstd", "otel", "dev", "test"] + +[package.metadata.requires-dev] +dev = [{ name = "claude-agent-sdk", specifier = ">=0.1.50" }] [[package]] name = "pycparser" @@ -837,18 +883,6 @@ crypto = [ { name = "cryptography" }, ] -[[package]] -name = "python-dateutil" -version = "2.9.0.post0" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "six" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/66/c0/0c8b6ad9f17a802ee498c46e004a0eb49bc148f2fd230864601a86dcf6db/python-dateutil-2.9.0.post0.tar.gz", hash = "sha256:37dd54208da7e1cd875388217d5e00ebd4179249f90fb72437e91a35459a0ad3", size = 342432, upload-time = "2024-03-01T18:36:20.211Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload-time = "2024-03-01T18:36:18.57Z" }, -] - [[package]] name = "python-dotenv" version = "1.2.4" @@ -1040,15 +1074,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/d1/b7/b95708304cd49b7b6f82fdd039f1748b66ec2b21d6a45180910802f1abf1/rpds_py-0.30.0-pp311-pypy311_pp73-musllinux_1_2_x86_64.whl", hash = "sha256:ac37f9f516c51e5753f27dfdef11a88330f04de2d564be3991384b2f3535d02e", size = 562191, upload-time = "2025-11-30T20:24:36.853Z" }, ] -[[package]] -name = "six" -version = "1.17.0" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/94/e7/b2c673351809dca68a0e064b6af791aa332cf192da575fd474ed7d6f16a2/six-1.17.0.tar.gz", hash = "sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81", size = 34031, upload-time = "2024-12-04T17:35:28.174Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" }, -] - [[package]] name = "sniffio" version = "1.3.1" diff --git a/openfeature-provider/pyproject.toml b/openfeature-provider/pyproject.toml index 2e2885b3d..4aecc0922 100644 --- a/openfeature-provider/pyproject.toml +++ b/openfeature-provider/pyproject.toml @@ -27,7 +27,7 @@ dependencies = [ # single-call API. Pinned to the posthog major this provider is released and # tested against (both ship from this repo); bump the upper bound when moving # the provider to a new posthog major. - "posthog>=7.0.0,<8.0.0", + "posthog>=7.0.0,<9.0.0", "openfeature-sdk>=0.8.0", ] diff --git a/posthog/__init__.py b/posthog/__init__.py index 3b5f1f876..cf5a54e94 100644 --- a/posthog/__init__.py +++ b/posthog/__init__.py @@ -10,8 +10,9 @@ OptionalSetArgs, ) from posthog.capture_compression import CaptureCompression as CaptureCompression -from posthog.capture_mode import CaptureMode as CaptureMode +from posthog.capture_send import CaptureError as CaptureError from posthog.client import Client +from posthog.utils import _is_personal_api_key from posthog.tracing.span import Span as Span from posthog.async_client import AsyncClient as AsyncClient from posthog.async_client import AsyncPosthog as AsyncPosthog @@ -52,6 +53,12 @@ from posthog.contexts import ( get_tags as inner_get_tags, ) +from posthog.contexts import ( + set_context_option as inner_set_context_option, +) +from posthog.contexts import ( + get_context_options as inner_get_context_options, +) from posthog.exception_utils import ( DEFAULT_CODE_VARIABLES_DETECT_SECRETS, DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS, @@ -300,6 +307,47 @@ def get_tags() -> Dict[str, Any]: return inner_get_tags() +def set_context_option(key: str, value: Any) -> None: + """ + Set a capture option for every event captured within the current context. + + Context options fill options an event leaves unset, before ``before_send`` + runs, so the hook sees them. They override ``super_options``. An event's + own ``options`` override them, and ``before_send`` can change them. They + never set ``process_person_profile`` on identify-style events, such as + ``$identify`` or ``$set``, whose distinct ID the SDK did not generate: + those default it to ``True``. + + Args: + key: The option name, such as ``"process_person_profile"`` + value: The option value, sent as given + + Examples: + ```python + from posthog import new_context, set_context_option + with new_context(): + set_context_option("process_person_profile", False) + ``` + + Category: + Contexts + """ + return inner_set_context_option(key, value) + + +def get_context_options() -> Dict[str, Any]: + """ + Get all capture options from the current context. + + Returns: + Dict of all capture options in the current context + + Category: + Contexts + """ + return inner_get_context_options() + + """Settings. These module-level settings configure the legacy global PostHog client used by @@ -314,8 +362,11 @@ def get_tags() -> Dict[str, Any]: disabled no-op global client. host: PostHog ingestion host. Defaults to the US ingestion endpoint when not set. - on_error: Optional callback invoked by background consumers when event upload - fails. Keep it short and non-blocking. Lifecycle methods can be called + on_error: Optional callback ``(error, batch)`` invoked when event upload + fails: by background consumers, or on the calling thread in ``sync_mode``. + Capture failures arrive as ``CaptureError``. Without it, each failed batch + logs one aggregate line. A capture that fails inside the callback logs that + line instead of calling it again. Keep it short and non-blocking. Lifecycle methods can be called directly and will be deferred, but the callback must not wait for another thread or task that calls ``flush()``, ``join()``, or ``shutdown()``. debug: Enable verbose SDK logging and re-raise errors from public APIs. @@ -338,7 +389,18 @@ def get_tags() -> Dict[str, Any]: feature_flags_request_max_retries: Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries. - super_properties: Properties merged into every captured event. + super_properties: Properties for every captured event. They fill only + keys the event leaves unset, before ``before_send`` runs. ``$set``, + ``$set_once``, ``$groups`` and ``$group_set`` fill one level deep. An + event's own properties and context tags override them, and + ``before_send`` can change or remove them. + super_options: Capture options for every captured event, such as + ``{"cookieless_mode": True}``. They fill only options the event leaves + unset, before ``before_send`` runs. An event's own ``options`` and + context options override them, and ``before_send`` can change them. + They never set ``process_person_profile`` on identify-style events, + such as ``$identify`` or ``$set``, whose distinct ID the SDK did not + generate: those default it to ``True``. metrics: Config dict for the ``client.metrics`` API (``service_name``, ``service_version``, ``environment``, ``flush_interval``, ...). Applied when ``setup()`` builds the global client, or on a later ``setup()`` @@ -369,7 +431,9 @@ def get_tags() -> Dict[str, Any]: project_root: Root path used to determine in-app exception stack frames. privacy_mode: Capture AI usage metadata without prompt inputs or outputs. before_send: Optional callback that can modify or drop events before upload. - Return ``None`` to drop an event. + Return ``None`` to drop an event. Context tags, context options, + ``super_properties`` and ``super_options`` fill in before it runs, so + it can change or remove them. enable_local_evaluation: Whether to poll feature flag definitions for local evaluation when a personal API key is configured. flag_definition_cache_provider: Optional external cache provider for sharing @@ -379,9 +443,11 @@ def get_tags() -> Dict[str, Any]: capture_trace_context: 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()``. Explicit ``$trace_id``/``$span_id`` values passed in - ``properties`` win. Exception events always attach these IDs regardless - of this setting. Defaults to False. + ``capture_ai()``. They fill after context tags and ``super_properties``, + before ``before_send``. A ``$trace_id`` or ``$span_id`` from the event, a + context tag or ``super_properties`` stops the SDK adding either ID. + Exception events always attach these IDs regardless of this setting. + Defaults to False. code_variables_mask_patterns: Variable-name patterns to mask when capturing code variables. code_variables_ignore_patterns: Variable-name patterns to omit when capturing @@ -419,6 +485,7 @@ def get_tags() -> Dict[str, Any]: feature_flags_request_timeout_seconds = 3 # type: float feature_flags_request_max_retries = 1 # type: int super_properties = None # type: Optional[Dict] +super_options = None # type: Optional[Dict] metrics = None # type: Optional[Dict] traces = None # type: Optional[Dict] enable_exception_autocapture = False # type: bool @@ -432,11 +499,8 @@ def get_tags() -> Dict[str, Any]: # We recommend setting this to False if you are only using the personalApiKey for evaluating remote config payloads via `get_remote_config_payload` and not using local evaluation. enable_local_evaluation = True # type: bool flag_definition_cache_provider = None # type: Optional[FlagDefinitionCacheProvider] -# Capture wire protocol for the global client. None defers to POSTHOG_CAPTURE_MODE -# then CaptureMode.V0. See posthog.capture_mode.CaptureMode. -capture_mode = None # type: Optional[CaptureMode] -# Routes AI SDK wrapper events through the dedicated AI capture lane, skips -# truncation, and passes media unredacted. `privacy_mode` always wins. +# 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 # Deprecated aliases for `enable_full_ai_capture`. _use_ai_lane = False # type: bool @@ -646,6 +710,7 @@ def group_identify( uuid: Optional[str] = None, disable_geoip: Optional[bool] = None, distinct_id: Optional[ID_TYPES] = None, + options: Optional[Dict[str, Any]] = None, ) -> Optional[str]: """ Set properties on a group. @@ -661,6 +726,8 @@ def group_identify( uuid: Optional UUID for the event disable_geoip: Whether to disable GeoIP lookup distinct_id: Optional distinct ID of the user performing the action + options: Optional capture options for the event, sent as given. + ``process_person_profile`` is ``True`` unless this call sets it. Examples: ```python @@ -684,6 +751,7 @@ def group_identify( uuid=uuid, disable_geoip=disable_geoip, distinct_id=distinct_id, + options=options, ) @@ -693,6 +761,7 @@ def alias( timestamp: Optional[Union[datetime.datetime, str]] = None, uuid: Optional[str] = None, disable_geoip: Optional[bool] = None, + options: Optional[Dict[str, Any]] = None, ) -> Optional[str]: """ Associate user behaviour before and after they e.g. register, login, or perform some other identifying action. @@ -704,6 +773,8 @@ def alias( datetimes and parseable ISO timestamp strings are converted to UTC. uuid: Optional UUID for the event disable_geoip: Whether to disable GeoIP lookup + options: Optional capture options for the event, sent as given. + ``process_person_profile`` is ``True`` unless this call sets it. Details: To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like "Which marketing channels leads to users churning after a month?" or "What do users do on our website before signing up?". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action. @@ -725,11 +796,14 @@ def alias( timestamp=timestamp, uuid=uuid, disable_geoip=disable_geoip, + options=options, ) def capture_exception( exception: Optional[ExceptionArg] = None, + *, + level: Optional[str] = None, **kwargs: Unpack[OptionalCaptureArgs], ) -> Optional[str]: """ @@ -737,10 +811,12 @@ def capture_exception( Args: exception: The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` + level: The ``$exception_level``, such as ``"warning"`` or ``"fatal"``. + Defaults to ``"error"``. An unknown value counts as unset. **kwargs: Optional capture arguments including distinct_id, properties, - timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. - Overriding reserved exception properties through ``properties`` is - deprecated and will stop working in the next major version. + timestamp, uuid, groups, flags, send_feature_flags, disable_geoip, and options. + Reserved exception properties in ``properties``, such as + ``$exception_list`` and ``$exception_level``, are ignored. Details: Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the "traceback"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError("Some Error"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`. @@ -758,7 +834,7 @@ def capture_exception( Events """ - return _proxy("capture_exception", exception=exception, **kwargs) + return _proxy("capture_exception", exception=exception, level=level, **kwargs) def feature_enabled( @@ -1444,6 +1520,7 @@ def setup() -> Client: feature_flags_request_timeout_seconds=feature_flags_request_timeout_seconds, feature_flags_request_max_retries=feature_flags_request_max_retries, super_properties=super_properties, + super_options=super_options, metrics=metrics, traces=traces, # TODO: Currently this monitoring begins only when the Client is initialised (which happens when you do something with the SDK) @@ -1467,12 +1544,15 @@ def setup() -> Client: exception_autocapture_bucket_size=exception_autocapture_bucket_size, exception_autocapture_refill_rate=exception_autocapture_refill_rate, exception_autocapture_refill_interval_seconds=exception_autocapture_refill_interval_seconds, - capture_mode=capture_mode, ) # Always set in case user changes it. Preserve Client's auto-disabled state - # for API keys that become empty after trimming. - default_client.disabled = disabled or not default_client.api_key + # for API keys that are empty after trimming or personal (`phx_`). + default_client.disabled = ( + disabled + or not default_client.api_key + or _is_personal_api_key(default_client.api_key) + ) default_client.debug = debug default_client.privacy_mode = bool(privacy_mode) default_client._set_before_send(before_send) diff --git a/posthog/_async_consumer.py b/posthog/_async_consumer.py index 87f86f652..d2dc5e75d 100644 --- a/posthog/_async_consumer.py +++ b/posthog/_async_consumer.py @@ -9,11 +9,12 @@ from dataclasses import dataclass from typing import Any, Optional -from ._async_request import async_batch_post, async_send_v1_batch +from ._async_request import async_send_v1_batch from .capture_compression import CaptureCompression -from .capture_mode import CaptureMode +from .capture_event import _EventDefaults +from .capture_send import _CAPTURE_V1_PATH, _capture_loss_message from .consumer import BATCH_SIZE_LIMIT, MAX_MSG_SIZE -from .request import APIError, DatetimeSerializer, EVENTS_ENDPOINT +from .request import DatetimeSerializer _STOP = object() _PROCESSING_EVENT = contextvars.ContextVar( @@ -37,6 +38,7 @@ async def _run_outside_processing_event(awaitable): class _QueuedEvent: event: dict[str, Any] context: contextvars.Context + defaults: Optional[_EventDefaults] = None async def _invoke_callback(callback, *args): @@ -48,8 +50,37 @@ async def _invoke_callback(callback, *args): return result +# True while an SDK-invoked `on_error` runs, so a capture that fails inside the +# callback logs instead of re-entering it. +_IN_ON_ERROR: contextvars.ContextVar[bool] = contextvars.ContextVar( + "posthog_in_on_error", default=False +) + + +async def _report_capture_failure( + on_error: Optional[Callable[..., Any]], + log: logging.Logger, + error: Exception, + batch: list[dict[str, Any]], + endpoint: str, +) -> None: + """Hand a failed send to `on_error`, or log one aggregate line without one.""" + if on_error is None or _IN_ON_ERROR.get(): + log.error(_capture_loss_message(error, max(1, len(batch)), endpoint)) + return + token = _IN_ON_ERROR.set(True) + try: + await _invoke_callback(on_error, error, batch) + except Exception as callback_error: + log.error("on_error handler failed (%s)", type(callback_error).__name__) + finally: + _IN_ON_ERROR.reset(token) + + async def _serialized_event_size(event: dict[str, Any]) -> int: - serialized = await asyncio.to_thread(json.dumps, event, cls=DatetimeSerializer) + serialized = await asyncio.to_thread( + json.dumps, event, cls=DatetimeSerializer, allow_nan=False + ) return len(serialized.encode()) @@ -65,16 +96,18 @@ def __init__( *, host: Optional[str], on_error: Optional[Callable[[Exception, list[dict[str, Any]]], Any]], - process_event: Callable[[dict[str, Any]], Awaitable[Optional[dict[str, Any]]]], + process_event: Callable[ + [dict[str, Any], Optional[_EventDefaults]], + Awaitable[Optional[dict[str, Any]]], + ], flush_at: int, flush_interval: float, - gzip: bool, retries: int, timeout: float, historical_migration: bool, - capture_mode: CaptureMode, capture_compression: CaptureCompression, - http_client: Optional[Any], + endpoint: str = _CAPTURE_V1_PATH, + max_msg_size: int = MAX_MSG_SIZE, ) -> None: self.queue = queue self.api_key = api_key @@ -83,13 +116,12 @@ def __init__( self.process_event = process_event self.flush_at = flush_at self.flush_interval = flush_interval - self.gzip = gzip self.retries = max(0, retries) self.timeout = timeout self.historical_migration = historical_migration - self.capture_mode = capture_mode self.capture_compression = capture_compression - self.http_client = http_client + self.endpoint = endpoint + self.max_msg_size = max_msg_size self._carryover: Optional[tuple[dict[str, Any], int]] = None self._flush_event = asyncio.Event() @@ -137,11 +169,11 @@ async def _get_or_flush(self, timeout: float) -> tuple[Any, bool]: return None, False async def _process_queued_event( - self, event: dict[str, Any] + self, queued: _QueuedEvent ) -> Optional[dict[str, Any]]: token = _PROCESSING_EVENT.set(True) try: - return await self.process_event(event) + return await self.process_event(queued.event, queued.defaults) finally: _PROCESSING_EVENT.reset(token) @@ -149,74 +181,24 @@ async def upload(self, batch: list[dict[str, Any]]) -> None: try: await self.request(batch) except Exception as error: - self.log.error( - "async capture upload failed (%s, status=%s)", - type(error).__name__, - getattr(error, "status", None), + await _report_capture_failure( + self.on_error, self.log, error, batch, self.endpoint ) - if self.on_error: - try: - await _invoke_callback(self.on_error, error, batch) - except Exception as callback_error: - self.log.error( - "on_error handler failed (%s)", type(callback_error).__name__ - ) finally: for _ in batch: self.queue.task_done() - async def _prepare_queued_event( - self, queued: _QueuedEvent - ) -> Optional[tuple[dict[str, Any], int]]: - try: - process_task = queued.context.run( - asyncio.create_task, self._process_queued_event(queued.event) - ) - item = await process_task - except Exception as error: - self.log.error( - "unable to process queued event, dropping (%s)", - type(error).__name__, - ) - self.queue.task_done() - return None - - if item is None: - self.queue.task_done() - return None - - try: - item_size = await _serialized_event_size(item) - except Exception: - self.log.error("unable to serialize queued event for sizing, dropping") - self.queue.task_done() - return None - - if item_size > MAX_MSG_SIZE: - self.log.error( - "Event %s (%d bytes) exceeds the %dKiB limit, dropping.", - item.get("event"), - item_size, - MAX_MSG_SIZE // 1024, - ) - self.queue.task_done() - return None - return item, item_size - - def _take_carryover(self, items: list[dict[str, Any]]) -> int: - if self._carryover is not None: - carried_item, carried_size = self._carryover - self._carryover = None - items.append(carried_item) - return carried_size - return 0 - async def next(self) -> tuple[list[dict[str, Any]], bool]: items: list[dict[str, Any]] = [] + total_size = 0 stop = False started = asyncio.get_running_loop().time() - total_size = self._take_carryover(items) + if self._carryover is not None: + carried_item, carried_size = self._carryover + self._carryover = None + items.append(carried_item) + total_size = carried_size while len(items) < self.flush_at: remaining = self.flush_interval - ( @@ -234,10 +216,42 @@ async def next(self) -> tuple[list[dict[str, Any]], bool]: stop = True break - prepared = await self._prepare_queued_event(queued) - if prepared is None: + try: + process_task = queued.context.run( + asyncio.create_task, self._process_queued_event(queued) + ) + item = await process_task + except Exception as error: + self.log.error( + "unable to process queued event, dropping (%s)", + type(error).__name__, + ) + self.queue.task_done() + continue + + if item is None: + self.queue.task_done() + continue + + try: + item_size = await _serialized_event_size(item) + except Exception: + self.log.error("unable to serialize queued event for sizing, dropping") + self.queue.task_done() + continue + + if item_size > self.max_msg_size: + # Log only name and size: AI events may carry unredacted + # multimodal payloads that must not leak into logs. + self.log.error( + "Event %s (%d bytes) exceeds the %dKiB limit for %s, dropping.", + item.get("event"), + item_size, + self.max_msg_size // 1024, + self.endpoint, + ) + self.queue.task_done() continue - item, item_size = prepared if items and total_size + item_size > BATCH_SIZE_LIMIT: self._carryover = (item, item_size) @@ -250,50 +264,43 @@ async def next(self) -> tuple[list[dict[str, Any]], bool]: return items, stop async def request(self, batch: list[dict[str, Any]]) -> None: - if self.capture_mode == CaptureMode.V1: - await async_send_v1_batch( - self.api_key, - self.host, - batch, - compression=self.capture_compression, - timeout=self.timeout, - max_retries=self.retries, - historical_migration=self.historical_migration, - ) - return + await async_send_v1_batch( + self.api_key, + self.host, + batch, + compression=self.capture_compression, + timeout=self.timeout, + max_retries=self.retries, + historical_migration=self.historical_migration, + path=self.endpoint, + ) - last_error: Optional[Exception] = None - for attempt in range(self.retries + 1): - try: - await async_batch_post( - self.api_key, - self.host, - batch=batch, - path=EVENTS_ENDPOINT, - gzip=self.gzip, - timeout=self.timeout, - historical_migration=self.historical_migration, - client=self.http_client, - ) - return - except Exception as error: - last_error = error - if not self._is_retryable(error) or attempt >= self.retries: - raise - retry_after = getattr(error, "retry_after", None) - delay = max( - min(2**attempt, 30), - min(retry_after, 30) if retry_after and retry_after > 0 else 0, - ) - await asyncio.sleep(delay) - - if last_error is not None: # pragma: no cover - loop always raises first - raise last_error - - @staticmethod - def _is_retryable(error: Exception) -> bool: - if not isinstance(error, APIError): - return True - if not isinstance(error.status, int): - return False - return not (400 <= error.status < 500 and error.status not in (408, 429)) + +class _AsyncLane: + """One capture queue, the consumer tasks that drain it, and the endpoint they post to. + + The client owns one lane per traffic class (analytics, AI), so each gets + its own backpressure, timeout, size cap and compression. + """ + + def __init__( + self, + *, + name: str, + max_queue_size: int, + endpoint: str, + max_msg_size: int, + timeout: float, + capture_compression: CaptureCompression, + ) -> None: + self.name = name + self.queue: asyncio.Queue[Any] = asyncio.Queue(max_queue_size) + self.endpoint = endpoint + self.max_msg_size = max_msg_size + self.timeout = timeout + self.capture_compression = capture_compression + self.consumers: list[_AsyncConsumer] = [] + self.worker_tasks: list[asyncio.Task[None]] = [] + + def pending_items(self) -> int: + return int(getattr(self.queue, "_unfinished_tasks", self.queue.qsize())) diff --git a/posthog/_async_request.py b/posthog/_async_request.py index ff407687f..2cb72b1c6 100644 --- a/posthog/_async_request.py +++ b/posthog/_async_request.py @@ -2,16 +2,12 @@ import asyncio import json -import logging -import zlib from datetime import datetime, timezone -from gzip import GzipFile -from io import BytesIO from typing import Any, Optional -from urllib.parse import quote, urljoin, urlsplit +from urllib.parse import quote from .capture_compression import CaptureCompression -from .capture_v1 import _parse_retry_after, _send_v1_batch +from .capture_send import _CAPTURE_V1_PATH, _parse_retry_after, _send_v1_batch from .request import ( APIError, DatetimeSerializer, @@ -41,54 +37,6 @@ def _build_client(host: Optional[str] = None): return httpx_module.AsyncClient(base_url=base_url, follow_redirects=False) -def _serialize_v0_body( - api_key: str, gzip_enabled: bool, body: dict[str, Any] -) -> tuple[str | bytes, dict[str, str]]: - payload = { - **body, - "sent_at": datetime.now(tz=timezone.utc).isoformat(), - "api_key": api_key, - } - serialized = json.dumps(payload, cls=DatetimeSerializer) - data: str | bytes = serialized - headers = {"Content-Type": "application/json", "User-Agent": USER_AGENT} - - if gzip_enabled: - try: - buf = BytesIO() - with GzipFile(fileobj=buf, mode="w") as gz: - gz.write(serialized.encode("utf-8")) - data = buf.getvalue() - headers["Content-Encoding"] = "gzip" - except (OSError, zlib.error) as exc: - logging.getLogger("posthog").warning( - "failed to gzip async request body, sending uncompressed: %s", exc - ) - - return data, headers - - -def _origin(url: str) -> tuple[str, str, Optional[int]]: - parsed = urlsplit(url) - port = parsed.port - if port is None: - port = 443 if parsed.scheme.lower() == "https" else 80 - return parsed.scheme.lower(), (parsed.hostname or "").lower(), port - - -def _same_origin_redirect_url( - base_url: str, current_url: str, location: str -) -> Optional[str]: - target = urlsplit(urljoin(current_url, location)) - if _origin(target.geturl()) != _origin(base_url): - return None - return ( - urlsplit(base_url) - ._replace(path=target.path or "/", query=target.query, fragment="") - .geturl() - ) - - def _serialize_flags_body( project_api_key: str, body: dict[str, Any] ) -> tuple[str, dict[str, str]]: @@ -196,55 +144,6 @@ async def async_remote_config( await http_client.aclose() -async def async_batch_post( - api_key: str, - host: Optional[str], - *, - batch: list[dict[str, Any]], - path: str, - gzip: bool = False, - timeout: float = 15, - historical_migration: bool = False, - client: Optional[Any] = None, -) -> None: - """Post one legacy capture batch without blocking the event loop.""" - if not path.startswith("/") or "://" in path: - raise ValueError("async capture paths must be relative") - - data, headers = await asyncio.to_thread( - _serialize_v0_body, - api_key, - gzip, - { - "batch": batch, - "historical_migration": historical_migration, - }, - ) - - owns_client = client is None - http_client = client or _build_client(host) - try: - logging.getLogger("posthog").debug("making async capture request") - base_url = remove_trailing_slash(normalize_host(host)) - # Absolute URLs avoid reapplying an HTTPX base_url path on redirects. - request_url = f"{base_url}{path}" - for redirect_count in range(6): - response = await http_client.post( - request_url, content=data, headers=headers, timeout=timeout - ) - if response.status_code not in (307, 308): - _process_response(response) - return - - redirect_url = _capture_redirect_url( - base_url, request_url, response, redirect_count - ) - request_url = redirect_url - finally: - if owns_client: - await http_client.aclose() - - async def async_send_v1_batch( api_key: str, host: Optional[str], @@ -254,6 +153,7 @@ async def async_send_v1_batch( timeout: float, max_retries: int, historical_migration: bool, + path: str = _CAPTURE_V1_PATH, ) -> None: """Run the existing capture-v1 submitter off-loop to preserve wire parity.""" await asyncio.to_thread( @@ -265,18 +165,5 @@ async def async_send_v1_batch( timeout=timeout, max_retries=max_retries, historical_migration=historical_migration, + path=path, ) - - -def _capture_redirect_url( - base_url: str, request_url: str, response: Any, redirect_count: int -) -> str: - location = response.headers.get("Location") or response.headers.get("location") - redirect_url = ( - _same_origin_redirect_url(base_url, request_url, location) if location else None - ) - if redirect_url is None: - raise APIError(400, "Cross-origin or invalid redirect blocked") - if redirect_count >= 5: - raise APIError(400, "Too many capture redirects") - return redirect_url diff --git a/posthog/ai/anthropic/anthropic.py b/posthog/ai/anthropic/anthropic.py index 957cdd380..ee7204325 100644 --- a/posthog/ai/anthropic/anthropic.py +++ b/posthog/ai/anthropic/anthropic.py @@ -18,6 +18,7 @@ ToolInProgress as ToolInProgress, ) from ..utils import ( + _resolve_ai_client, call_llm_and_track_usage as call_llm_and_track_usage, merge_usage_stats as merge_usage_stats, ) @@ -30,7 +31,6 @@ handle_anthropic_tool_delta as handle_anthropic_tool_delta, ) from posthog.client import Client as PostHogClient -from posthog import setup _log = logging.getLogger("posthog") @@ -49,7 +49,7 @@ def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs): **kwargs: Additional arguments passed to the Anthropic client """ super().__init__(**kwargs) - self._ph_client = posthog_client or setup() + self._ph_client = _resolve_ai_client(posthog_client) self.messages = WrappedMessages(self) @@ -63,6 +63,7 @@ def create( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -74,6 +75,10 @@ def create( posthog_properties: Optional dictionary of extra properties to include in the event posthog_privacy_mode: Whether to redact sensitive information in tracking posthog_groups: Optional group analytics properties + posthog_options: Optional capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to Anthropic's messages.create """ @@ -87,6 +92,7 @@ def create( posthog_properties, posthog_privacy_mode, posthog_groups, + posthog_options=posthog_options, **kwargs, ) @@ -100,6 +106,7 @@ def create( posthog_groups, self._client.base_url, super().create, + posthog_options=posthog_options, **kwargs, ) @@ -110,6 +117,7 @@ def stream( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -121,6 +129,10 @@ def stream( posthog_properties: Additional properties to include with the usage event. posthog_privacy_mode: Whether to redact captured input and output. posthog_groups: Optional PostHog groups to associate with the event. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to Anthropic's ``messages.create`` API. Returns: @@ -157,6 +169,7 @@ def tracked_request(): accumulator.content_blocks, accumulator.accumulated_content, error=exc, + options=posthog_options, ) except Exception: # Telemetry must never replace the provider's own error. @@ -171,6 +184,7 @@ def tracked_request(): posthog_groups, kwargs, start_time, + options=posthog_options, ) setattr(manager, request_attribute, tracked_request) @@ -183,6 +197,7 @@ def _create_streaming( posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): start_time = time.time() @@ -203,6 +218,7 @@ def _create_streaming( accumulator.content_blocks, accumulator.accumulated_content, error=exc, + options=posthog_options, ) except Exception: # Telemetry must never replace the provider's own error. @@ -217,6 +233,7 @@ def _create_streaming( posthog_groups, kwargs, start_time, + options=posthog_options, ) def _track_streaming_response( @@ -229,6 +246,7 @@ def _track_streaming_response( posthog_groups: Optional[Dict[str, Any]], kwargs: Dict[str, Any], start_time: float, + options: Optional[Dict[str, Any]] = None, ): accumulator = _AnthropicStreamAccumulator() @@ -258,6 +276,7 @@ def generator(): accumulator.accumulated_content, stop_reason=accumulator.stop_reason, error=stream_error, + options=options, ) return _StreamWrapper(generator(), stream=response) @@ -276,6 +295,7 @@ def _capture_streaming_event( accumulated_content: str, stop_reason: Optional[str] = None, error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ): from posthog.ai.types import StreamingEventData from posthog.ai.anthropic.anthropic_converter import ( @@ -304,6 +324,7 @@ def _capture_streaming_event( groups=posthog_groups, stop_reason=stop_reason, error=error, + options=options, ) # Use the common capture function diff --git a/posthog/ai/anthropic/anthropic_async.py b/posthog/ai/anthropic/anthropic_async.py index baf13c821..60f267fc4 100644 --- a/posthog/ai/anthropic/anthropic_async.py +++ b/posthog/ai/anthropic/anthropic_async.py @@ -11,8 +11,6 @@ import uuid from typing import Any, Dict, List, Optional -from posthog import setup - from ..stream import AsyncStreamWrapper as AsyncStreamWrapper from ..types import ( StreamingContentBlock as StreamingContentBlock, @@ -20,6 +18,7 @@ ToolInProgress as ToolInProgress, ) from ..utils import ( + _resolve_ai_client, call_llm_and_track_usage_async as call_llm_and_track_usage_async, merge_usage_stats as merge_usage_stats, ) @@ -50,7 +49,7 @@ def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs): **kwargs: Additional arguments passed to the Anthropic client """ super().__init__(**kwargs) - self._ph_client = posthog_client or setup() + self._ph_client = _resolve_ai_client(posthog_client) self.messages = AsyncWrappedMessages(self) @@ -64,6 +63,7 @@ async def create( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -75,6 +75,10 @@ async def create( posthog_properties: Optional dictionary of extra properties to include in the event posthog_privacy_mode: Whether to redact sensitive information in tracking posthog_groups: Optional group analytics properties + posthog_options: Optional capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to Anthropic's messages.create """ @@ -88,6 +92,7 @@ async def create( posthog_properties, posthog_privacy_mode, posthog_groups, + posthog_options=posthog_options, **kwargs, ) @@ -101,6 +106,7 @@ async def create( posthog_groups, self._client.base_url, super().create, + posthog_options=posthog_options, **kwargs, ) @@ -111,6 +117,7 @@ def stream( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -122,6 +129,10 @@ def stream( posthog_properties: Additional properties to include with the usage event. posthog_privacy_mode: Whether to redact captured input and output. posthog_groups: Optional PostHog groups to associate with the event. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to Anthropic's async ``messages.create`` API. Returns: @@ -158,6 +169,7 @@ async def tracked_request(): accumulator.content_blocks, accumulator.accumulated_content, error=exc, + options=posthog_options, ) except Exception: # Telemetry must never replace the provider's own error. @@ -172,6 +184,7 @@ async def tracked_request(): posthog_groups, kwargs, start_time, + options=posthog_options, ) setattr(manager, request_attribute, tracked_request()) @@ -184,6 +197,7 @@ async def _create_streaming( posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): start_time = time.time() @@ -204,6 +218,7 @@ async def _create_streaming( accumulator.content_blocks, accumulator.accumulated_content, error=exc, + options=posthog_options, ) except Exception: # Telemetry must never replace the provider's own error. @@ -218,6 +233,7 @@ async def _create_streaming( posthog_groups, kwargs, start_time, + options=posthog_options, ) def _track_streaming_response( @@ -230,6 +246,7 @@ def _track_streaming_response( posthog_groups: Optional[Dict[str, Any]], kwargs: Dict[str, Any], start_time: float, + options: Optional[Dict[str, Any]] = None, ): accumulator = _AnthropicStreamAccumulator() @@ -259,6 +276,7 @@ async def generator(): accumulator.accumulated_content, stop_reason=accumulator.stop_reason, error=stream_error, + options=options, ) return AsyncStreamWrapper(generator(), stream=response) @@ -277,6 +295,7 @@ async def _capture_streaming_event( accumulated_content: str, stop_reason: Optional[str] = None, error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ): from posthog.ai.types import StreamingEventData from posthog.ai.anthropic.anthropic_converter import ( @@ -305,6 +324,7 @@ async def _capture_streaming_event( groups=posthog_groups, stop_reason=stop_reason, error=error, + options=options, ) # Use the common capture function diff --git a/posthog/ai/anthropic/anthropic_providers.py b/posthog/ai/anthropic/anthropic_providers.py index 8b816b162..2e8fe2806 100644 --- a/posthog/ai/anthropic/anthropic_providers.py +++ b/posthog/ai/anthropic/anthropic_providers.py @@ -9,8 +9,8 @@ from posthog.ai.anthropic.anthropic import WrappedMessages from posthog.ai.anthropic.anthropic_async import AsyncWrappedMessages +from posthog.ai.utils import _resolve_ai_client from posthog.client import Client as PostHogClient -from posthog import setup class AnthropicBedrock(anthropic.AnthropicBedrock): @@ -28,7 +28,7 @@ def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs): **kwargs: Arguments passed to ``anthropic.AnthropicBedrock``. """ super().__init__(**kwargs) - self._ph_client = posthog_client or setup() + self._ph_client = _resolve_ai_client(posthog_client) self.messages = WrappedMessages(self) @@ -47,7 +47,7 @@ def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs): **kwargs: Arguments passed to ``anthropic.AsyncAnthropicBedrock``. """ super().__init__(**kwargs) - self._ph_client = posthog_client or setup() + self._ph_client = _resolve_ai_client(posthog_client) self.messages = AsyncWrappedMessages(self) @@ -66,7 +66,7 @@ def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs): **kwargs: Arguments passed to ``anthropic.AnthropicVertex``. """ super().__init__(**kwargs) - self._ph_client = posthog_client or setup() + self._ph_client = _resolve_ai_client(posthog_client) self.messages = WrappedMessages(self) @@ -85,5 +85,5 @@ def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs): **kwargs: Arguments passed to ``anthropic.AsyncAnthropicVertex``. """ super().__init__(**kwargs) - self._ph_client = posthog_client or setup() + self._ph_client = _resolve_ai_client(posthog_client) self.messages = AsyncWrappedMessages(self) diff --git a/posthog/ai/claude_agent_sdk/__init__.py b/posthog/ai/claude_agent_sdk/__init__.py index 170a08c01..4e492d313 100644 --- a/posthog/ai/claude_agent_sdk/__init__.py +++ b/posthog/ai/claude_agent_sdk/__init__.py @@ -34,6 +34,7 @@ def instrument( privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None, + options: Optional[Dict[str, Any]] = None, ) -> PostHogClaudeAgentProcessor: """ Create a PostHog-instrumented query wrapper for the Claude Agent SDK. @@ -49,6 +50,10 @@ def instrument( privacy_mode: If True, redacts sensitive information in tracking. groups: Optional PostHog groups to associate with events. properties: Optional additional properties to include with all events. + options: Optional capture options for all events, such as + ``{"cookieless_mode": True}``. They win over context options and + ``super_options``. An event without a distinct ID always sends + ``process_person_profile: False``. Returns: PostHogClaudeAgentProcessor: A processor whose .query() method wraps claude_agent_sdk.query(). @@ -69,6 +74,7 @@ def instrument( privacy_mode=privacy_mode, groups=groups, properties=properties, + options=options, ) @@ -85,6 +91,7 @@ async def query( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, ): """ Drop-in replacement for claude_agent_sdk.query() with PostHog instrumentation. @@ -102,6 +109,11 @@ async def query( posthog_properties: Extra properties to include with all events. posthog_privacy_mode: If True, redacts sensitive content. posthog_groups: Optional PostHog groups. + posthog_options: Capture options for all events, such as + ``{"cookieless_mode": True}``. They win over context options and + ``super_options``. An event without a distinct ID always sends + ``process_person_profile: False``. Named so it does not clash with + ``options``, the Claude Agent SDK options. Example: ```python @@ -147,5 +159,6 @@ async def query( posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, + posthog_options=posthog_options, ): yield message diff --git a/posthog/ai/claude_agent_sdk/client.py b/posthog/ai/claude_agent_sdk/client.py index df1491b0f..f8fb124e6 100644 --- a/posthog/ai/claude_agent_sdk/client.py +++ b/posthog/ai/claude_agent_sdk/client.py @@ -67,6 +67,7 @@ def __init__( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, ): """ Initialize a stateful Claude Agent SDK client with PostHog instrumentation. @@ -83,6 +84,10 @@ def __init__( posthog_properties: Additional properties included on emitted AI events. posthog_privacy_mode: Whether to redact captured inputs, outputs, and tool data. posthog_groups: Optional PostHog groups to associate with emitted events. + posthog_options: Capture options for emitted AI events, such as + ``{"cookieless_mode": True}``. They win over context options and + ``super_options``. An event without a distinct ID always sends + ``process_person_profile: False``. """ from dataclasses import replace as dc_replace @@ -99,6 +104,7 @@ def __init__( privacy_mode=posthog_privacy_mode, groups=posthog_groups, properties=posthog_properties or {}, + options=posthog_options, ) self._trace_id = posthog_trace_id or str(uuid.uuid4()) self._distinct_id = posthog_distinct_id @@ -243,14 +249,12 @@ async def disconnect(self) -> None: **self._extra_props, } - if resolved_id is None: - properties["$process_person_profile"] = False - self._processor._capture_event( "$ai_trace", properties, resolved_id or self._trace_id, self._groups, + personless=resolved_id is None, ) try: diff --git a/posthog/ai/claude_agent_sdk/processor.py b/posthog/ai/claude_agent_sdk/processor.py index 0f86feeb0..ec9b46c3d 100644 --- a/posthog/ai/claude_agent_sdk/processor.py +++ b/posthog/ai/claude_agent_sdk/processor.py @@ -24,8 +24,7 @@ "Please install the Claude Agent SDK to use this feature: 'pip install claude-agent-sdk'" ) -from posthog import setup -from .formatting import ( +from posthog.ai.claude_agent_sdk.formatting import ( _append_assistant_output, _format_user_input, format_assistant_blocks as format_assistant_blocks, @@ -33,7 +32,9 @@ ) from posthog.ai.media import ensure_serializable as _ensure_serializable from posthog.ai.utils import ( + _ai_event_options, _capture_processor_event, + _resolve_ai_client, finalize_ai_content, with_privacy_mode as _with_privacy_mode, ) @@ -93,7 +94,31 @@ def process_stream_event(self, event: "StreamEvent") -> None: self._current.raw_usage = dict(usage) elif event_type == "message_delta" and self._current is not None: - self._process_usage_delta(raw) + usage = raw.get("usage", {}) + self._current.raw_usage = {**(self._current.raw_usage or {}), **usage} + # message_delta usage is cumulative: output tokens, and with server + # tools (web search, ...) the input and cache counts grow past the + # message_start values. Keep the larger count; a field the delta + # omits keeps the message_start value. + if usage.get("output_tokens"): + self._current.output_tokens = usage["output_tokens"] + for field_name in ( + "input_tokens", + "cache_read_input_tokens", + "cache_creation_input_tokens", + ): + delta_value = usage.get(field_name) + current_value = getattr(self._current, field_name) + if isinstance(delta_value, int) and delta_value > (current_value or 0): + setattr(self._current, field_name, delta_value) + server_tool_use = usage.get("server_tool_use") or {} + web_search_requests = server_tool_use.get("web_search_requests") + if isinstance(web_search_requests, int) and web_search_requests > 0: + self._current.web_search_count = web_search_requests + # Extract stop reason from message_delta + delta_stop_reason = raw.get("delta", {}).get("stop_reason") + if delta_stop_reason is not None: + self._current.stop_reason = delta_stop_reason elif event_type == "message_stop" and self._current is not None: self._current.end_time = time.time() @@ -101,38 +126,6 @@ def process_stream_event(self, event: "StreamEvent") -> None: self._last_model = self._current.model self._current = None - def _process_usage_delta(self, raw: Dict[str, Any]) -> None: - assert self._current is not None - usage = raw.get("usage", {}) - self._current.raw_usage = {**(self._current.raw_usage or {}), **usage} - # message_delta usage is cumulative: output tokens, and with server - # tools (web search, ...) the input and cache counts grow past the - # message_start values. Keep the larger count; a field the delta - # omits keeps the message_start value. - if usage.get("output_tokens"): - self._current.output_tokens = usage["output_tokens"] - self._update_cumulative_input_counts(usage) - server_tool_use = usage.get("server_tool_use") or {} - web_search_requests = server_tool_use.get("web_search_requests") - if isinstance(web_search_requests, int) and web_search_requests > 0: - self._current.web_search_count = web_search_requests - # Extract stop reason from message_delta - delta_stop_reason = raw.get("delta", {}).get("stop_reason") - if delta_stop_reason is not None: - self._current.stop_reason = delta_stop_reason - - def _update_cumulative_input_counts(self, usage: Dict[str, Any]) -> None: - assert self._current is not None - for field_name in ( - "input_tokens", - "cache_read_input_tokens", - "cache_creation_input_tokens", - ): - delta_value = usage.get(field_name) - current_value = getattr(self._current, field_name) - if isinstance(delta_value, int) and delta_value > (current_value or 0): - setattr(self._current, field_name, delta_value) - def set_model(self, model: str) -> None: self._last_model = model @@ -182,6 +175,7 @@ def __init__( privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None, + options: Optional[Dict[str, Any]] = None, ): """ Initialize a Claude Agent SDK query processor. @@ -193,12 +187,18 @@ def __init__( privacy_mode: Whether to redact captured inputs, outputs, and tool data. groups: Optional PostHog groups to associate with emitted events. properties: Additional properties included on emitted AI events. + options: Capture options for emitted AI events, such as + ``{"cookieless_mode": True}``. They win over a query's + ``posthog_options``, context options and ``super_options``. An + event without a distinct ID always sends + ``process_person_profile: False``. """ - self._client = client or setup() + self._client = _resolve_ai_client(client) self._distinct_id = distinct_id self._privacy_mode = privacy_mode self._groups = groups or {} self._properties = properties or {} + self._options = _ai_event_options(options) def _get_distinct_id( self, result: Optional["ResultMessage"] = None @@ -219,6 +219,8 @@ def _capture_event( properties: Dict[str, Any], distinct_id: Optional[str] = None, groups: Optional[Dict[str, Any]] = None, + personless: bool = False, + options: Optional[Dict[str, Any]] = None, ) -> None: _capture_processor_event( self._client, @@ -227,6 +229,9 @@ def _capture_event( default_properties=self._properties, distinct_id=distinct_id, groups=groups if groups is not None else self._groups, + personless=personless, + options=options, + default_options=self._options, ) async def query( @@ -242,6 +247,7 @@ async def query( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, ): """Drop-in replacement for claude_agent_sdk.query() with PostHog instrumentation. @@ -257,6 +263,9 @@ async def query( posthog_properties: Extra properties merged into all events for this query posthog_privacy_mode: Override privacy mode for this query posthog_groups: Override groups for this query + posthog_options: Capture options for all events of this query, such + as ``{"cookieless_mode": True}``. Named so it does not clash with + ``options``, the Claude Agent SDK options. """ from dataclasses import replace @@ -264,6 +273,7 @@ async def query( distinct_id_override = posthog_distinct_id or self._distinct_id trace_id = posthog_trace_id or str(uuid.uuid4()) extra_props = posthog_properties or {} + extra_options = _ai_event_options(posthog_options) # Per-call privacy can enable redaction, but cannot disable the # processor-level setting. This preserves the existing precedence. privacy = self._privacy_mode or posthog_privacy_mode is True @@ -275,36 +285,19 @@ async def query( elif not options.include_partial_messages: options = replace(options, include_partial_messages=True) - async for message in self._instrument_query( - prompt, - options, - transport, - distinct_id_override, - trace_id, - extra_props, - privacy, - groups, - ): - yield message - - async def _instrument_query( - self, - prompt: Any, - options: ClaudeAgentOptions, - transport: Any, - distinct_id_override: Any, - trace_id: str, - extra_props: Dict[str, Any], - privacy: bool, - groups: Dict[str, Any], - ): tracker = _GenerationTracker() query_start = time.time() generation_index = 0 current_generation_span_id: Optional[str] = None # Track input/output for generation events - initial_input, current_input = _query_inputs(prompt, options) + initial_input: List[Dict[str, Any]] = [] + if isinstance(prompt, str): + initial_input = [{"role": "user", "content": prompt}] + if options and options.system_prompt and isinstance(options.system_prompt, str): + initial_input = [ + {"role": "system", "content": options.system_prompt} + ] + initial_input # Two-slot input tracking: # - current_input: input for the generation currently in progress @@ -316,6 +309,7 @@ async def _instrument_query( # does not matter which side of message_stop the tool results land on. # Input is used by one generation only: a generation with nothing # queued has no input. + current_input: Optional[List[Dict[str, Any]]] = initial_input or None next_input: Optional[List[Dict[str, Any]]] = None # Accumulate assistant output per generation @@ -353,22 +347,35 @@ async def _instrument_query( extra_props, privacy, groups, + extra_options=extra_options, ) current_input = None pending_output = [] elif isinstance(message, AssistantMessage): - pending_output = self._process_assistant_message( - message, - tracker, - current_generation_span_id, - trace_id, - distinct_id_override, - extra_props, - privacy, - groups, - pending_output, - ) + tracker.set_model(message.model) + # Use the in-progress generation's span_id as parent for tool spans. + # AssistantMessage arrives before message_stop, so current_generation_span_id + # would be stale (from the previous turn). tracker.current_span_id gives us + # the correct in-progress generation. + parent_id = tracker.current_span_id or current_generation_span_id + for block in message.content: + if isinstance(block, ToolUseBlock): + self._emit_tool_span( + block, + trace_id, + parent_id, + distinct_id_override, + extra_props, + privacy, + groups, + extra_options=extra_options, + ) + if not _from_subagent(message): + # A subagent's own API calls are not this query's generations. + pending_output = _append_assistant_output( + pending_output, message.content + ) elif isinstance(message, UserMessage) and not _from_subagent(message): # UserMessages carry tool results; queue them as input for the @@ -382,17 +389,32 @@ async def _instrument_query( ) elif isinstance(message, ResultMessage): - self._process_query_result( + # Fallback: if no StreamEvents were received, emit a single + # generation from ResultMessage aggregate data + if not tracker.had_any_stream_events: + self._emit_generation_from_result( + message, + trace_id, + tracker.last_model, + query_start, + initial_input, + pending_output, + distinct_id_override, + extra_props, + privacy, + groups, + extra_options=extra_options, + ) + + self._emit_trace( message, - tracker, trace_id, query_start, - initial_input, - pending_output, distinct_id_override, extra_props, privacy, groups, + extra_options=extra_options, ) except Exception as e: @@ -400,79 +422,6 @@ async def _instrument_query( yield message - def _process_query_result( - self, - message: "ResultMessage", - tracker: _GenerationTracker, - trace_id: str, - query_start: float, - initial_input: List[Dict[str, Any]], - pending_output: List[Dict[str, Any]], - distinct_id_override: Any, - extra_props: Dict[str, Any], - privacy: bool, - groups: Dict[str, Any], - ) -> None: - # Fallback: if no StreamEvents were received, emit a single - # generation from ResultMessage aggregate data - if not tracker.had_any_stream_events: - self._emit_generation_from_result( - message, - trace_id, - tracker.last_model, - query_start, - initial_input, - pending_output, - distinct_id_override, - extra_props, - privacy, - groups, - ) - - self._emit_trace( - message, - trace_id, - query_start, - distinct_id_override, - extra_props, - privacy, - groups, - ) - - def _process_assistant_message( - self, - message: "AssistantMessage", - tracker: _GenerationTracker, - current_generation_span_id: Optional[str], - trace_id: str, - distinct_id: Any, - extra_props: Dict[str, Any], - privacy: bool, - groups: Dict[str, Any], - pending_output: List[Dict[str, Any]], - ) -> List[Dict[str, Any]]: - tracker.set_model(message.model) - # Use the in-progress generation's span_id as parent for tool spans. - # AssistantMessage arrives before message_stop, so current_generation_span_id - # would be stale (from the previous turn). tracker.current_span_id gives us - # the correct in-progress generation. - parent_id = tracker.current_span_id or current_generation_span_id - for block in message.content: - if isinstance(block, ToolUseBlock): - self._emit_tool_span( - block, - trace_id, - parent_id, - distinct_id, - extra_props, - privacy, - groups, - ) - if _from_subagent(message): - # A subagent's own API calls are not this query's generations. - return pending_output - return _append_assistant_output(pending_output, message.content) - def _emit_generation( self, gen: _GenerationData, @@ -484,6 +433,7 @@ def _emit_generation( extra_props: Dict[str, Any], privacy: bool, groups: Dict[str, Any], + extra_options: Optional[Dict[str, Any]] = None, ) -> None: resolved_id = self._resolve_distinct_id(distinct_id) latency = ( @@ -511,26 +461,6 @@ def _emit_generation( **extra_props, } - self._add_generation_content( - properties, input_messages, output_choices, privacy - ) - - _add_generation_usage(properties, gen) - - if resolved_id is None: - properties["$process_person_profile"] = False - - self._capture_event( - "$ai_generation", properties, resolved_id or trace_id, groups - ) - - def _add_generation_content( - self, - properties: Dict[str, Any], - input_messages: Optional[List[Dict[str, Any]]], - output_choices: Optional[List[Dict[str, Any]]], - privacy: bool, - ) -> None: if input_messages is not None: properties["$ai_input"] = _with_privacy_mode( self._client, @@ -544,6 +474,29 @@ def _add_generation_content( finalize_ai_content(output_choices, self._client), ) + if gen.cache_read_input_tokens: + properties["$ai_cache_read_input_tokens"] = gen.cache_read_input_tokens + if gen.cache_creation_input_tokens: + properties["$ai_cache_creation_input_tokens"] = ( + gen.cache_creation_input_tokens + ) + if gen.web_search_count: + properties["$ai_web_search_count"] = gen.web_search_count + if gen.raw_usage: + properties["$ai_usage"] = gen.raw_usage + + if gen.stop_reason is not None: + properties["$ai_stop_reason"] = gen.stop_reason + + self._capture_event( + "$ai_generation", + properties, + resolved_id or trace_id, + groups, + personless=resolved_id is None, + options=extra_options, + ) + def _emit_generation_from_result( self, result: "ResultMessage", @@ -556,6 +509,7 @@ def _emit_generation_from_result( extra_props: Dict[str, Any], privacy: bool, groups: Dict[str, Any], + extra_options: Optional[Dict[str, Any]] = None, ) -> None: """Fallback: emit a single generation from ResultMessage aggregate data.""" resolved_id = self._resolve_distinct_id(distinct_id) @@ -585,17 +539,38 @@ def _emit_generation_from_result( **extra_props, } - self._add_generation_content( - properties, input_messages, output_choices, privacy - ) + if input_messages is not None: + properties["$ai_input"] = _with_privacy_mode( + self._client, + privacy, + finalize_ai_content(input_messages, self._client), + ) + if output_choices is not None: + properties["$ai_output_choices"] = _with_privacy_mode( + self._client, + privacy, + finalize_ai_content(output_choices, self._client), + ) - _add_result_usage(properties, usage, result) + cache_read = usage.get("cache_read_input_tokens") + cache_creation = usage.get("cache_creation_input_tokens") + if cache_read: + properties["$ai_cache_read_input_tokens"] = cache_read + if cache_creation: + properties["$ai_cache_creation_input_tokens"] = cache_creation + if usage: + properties["$ai_usage"] = dict(usage) - if resolved_id is None: - properties["$process_person_profile"] = False + if result.total_cost_usd is not None: + properties["$ai_total_cost_usd"] = result.total_cost_usd self._capture_event( - "$ai_generation", properties, resolved_id or trace_id, groups + "$ai_generation", + properties, + resolved_id or trace_id, + groups, + personless=resolved_id is None, + options=extra_options, ) def _emit_tool_span( @@ -607,6 +582,7 @@ def _emit_tool_span( extra_props: Dict[str, Any], privacy: bool, groups: Dict[str, Any], + extra_options: Optional[Dict[str, Any]] = None, ) -> None: resolved_id = self._resolve_distinct_id(distinct_id) @@ -626,10 +602,14 @@ def _emit_tool_span( _ensure_serializable(block.input), self._client ) - if resolved_id is None: - properties["$process_person_profile"] = False - - self._capture_event("$ai_span", properties, resolved_id or trace_id, groups) + self._capture_event( + "$ai_span", + properties, + resolved_id or trace_id, + groups, + personless=resolved_id is None, + options=extra_options, + ) def _emit_trace( self, @@ -640,6 +620,7 @@ def _emit_trace( extra_props: Dict[str, Any], privacy: bool, groups: Dict[str, Any], + extra_options: Optional[Dict[str, Any]] = None, ) -> None: resolved_id = self._resolve_distinct_id(distinct_id, result) latency = ( @@ -661,10 +642,14 @@ def _emit_trace( if result.total_cost_usd is not None: properties["$ai_total_cost_usd"] = result.total_cost_usd - if resolved_id is None: - properties["$process_person_profile"] = False - - self._capture_event("$ai_trace", properties, resolved_id or trace_id, groups) + self._capture_event( + "$ai_trace", + properties, + resolved_id or trace_id, + groups, + personless=resolved_id is None, + options=extra_options, + ) # Flush to ensure events are sent before process exits try: @@ -710,47 +695,3 @@ def _promote_input( ) -> tuple[Optional[List[Dict[str, Any]]], None]: """Make queued input the input of the generation that is starting.""" return (current_input if next_input is None else next_input), None - - -def _query_inputs( - prompt: Any, options: ClaudeAgentOptions -) -> tuple[List[Dict[str, Any]], Optional[List[Dict[str, Any]]]]: - initial_input: List[Dict[str, Any]] = [] - if isinstance(prompt, str): - initial_input = [{"role": "user", "content": prompt}] - if options and options.system_prompt and isinstance(options.system_prompt, str): - initial_input = [ - {"role": "system", "content": options.system_prompt} - ] + initial_input - - return initial_input, initial_input or None - - -def _add_generation_usage(properties: Dict[str, Any], gen: _GenerationData) -> None: - if gen.cache_read_input_tokens: - properties["$ai_cache_read_input_tokens"] = gen.cache_read_input_tokens - if gen.cache_creation_input_tokens: - properties["$ai_cache_creation_input_tokens"] = gen.cache_creation_input_tokens - if gen.web_search_count: - properties["$ai_web_search_count"] = gen.web_search_count - if gen.raw_usage: - properties["$ai_usage"] = gen.raw_usage - - if gen.stop_reason is not None: - properties["$ai_stop_reason"] = gen.stop_reason - - -def _add_result_usage( - properties: Dict[str, Any], usage: Dict[str, Any], result: "ResultMessage" -) -> None: - cache_read = usage.get("cache_read_input_tokens") - cache_creation = usage.get("cache_creation_input_tokens") - if cache_read: - properties["$ai_cache_read_input_tokens"] = cache_read - if cache_creation: - properties["$ai_cache_creation_input_tokens"] = cache_creation - if usage: - properties["$ai_usage"] = dict(usage) - - if result.total_cost_usd is not None: - properties["$ai_total_cost_usd"] = result.total_cost_usd diff --git a/posthog/ai/gemini/_shared.py b/posthog/ai/gemini/_shared.py index 367b7ba22..4c30a6320 100644 --- a/posthog/ai/gemini/_shared.py +++ b/posthog/ai/gemini/_shared.py @@ -9,11 +9,13 @@ "Please install the Google Gemini SDK to use this feature: 'pip install google-genai'" ) -from ... import setup from ...client import Client as PostHogClient from ..types import StreamingEventData, TokenUsage from ..utils import ( + _user_distinct_id, + _ai_event_options, _capture_ai_event, + _resolve_ai_client, capture_streaming_event, finalize_ai_content, _format_ai_error, @@ -29,15 +31,6 @@ _GEMINI_BASE_URL = "https://generativelanguage.googleapis.com" -def _resolve_posthog_client( - posthog_client: Optional[PostHogClient], -) -> PostHogClient: - client = posthog_client or setup() - if client is None: - raise ValueError("posthog_client is required for PostHog tracking") - return client - - def _build_gemini_client_args( *, api_key: Optional[str], @@ -142,13 +135,15 @@ def _initialize_policy( posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], + posthog_options: Optional[Dict[str, Any]] = None, provider_client: Optional[Any] = None, ) -> None: - self._ph_client = _resolve_posthog_client(posthog_client) + self._ph_client = _resolve_ai_client(posthog_client) self._default_distinct_id = posthog_distinct_id self._default_properties = posthog_properties or {} self._default_privacy_mode = posthog_privacy_mode self._default_groups = posthog_groups + self._default_options = _ai_event_options(posthog_options) # Every surface of one PostHog client (sync models, aio models, files) # shares a single provider client rather than opening its own. @@ -192,6 +187,12 @@ def _merge_posthog_params( trace_id = call_trace_id if call_trace_id is not None else str(uuid.uuid4()) return distinct_id, trace_id, properties, privacy_mode, groups + def _merge_posthog_options( + self, call_options: Optional[Dict[str, Any]] + ) -> Dict[str, Any]: + """Merge call-level capture options over the client defaults, key by key.""" + return {**self._default_options, **_ai_event_options(call_options)} + def _capture_streaming_event( self, model: str, @@ -207,6 +208,7 @@ def _capture_streaming_event( output: Any, stop_reason: Optional[str] = None, error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ) -> None: formatted_input = merge_system_prompt( {"contents": contents, **kwargs}, "gemini" @@ -227,6 +229,7 @@ def _capture_streaming_event( groups=groups, stop_reason=stop_reason, error=error, + options=options, ) capture_streaming_event(self._ph_client, event_data) @@ -243,6 +246,7 @@ def _capture_embedding_outcome( response: Any, error: Optional[Exception], latency: float, + options: Optional[Dict[str, Any]] = None, ) -> None: input_tokens = ( extract_gemini_embedding_token_count(response) if response else None @@ -271,13 +275,12 @@ def _capture_embedding_outcome( self._ph_client, privacy_mode, error ) - if distinct_id is None: - event_properties["$process_person_profile"] = False - _capture_ai_event( self._ph_client, "$ai_embedding", - distinct_id=distinct_id or trace_id, + distinct_id=_user_distinct_id(distinct_id) or trace_id, properties=event_properties, groups=groups, + personless=_user_distinct_id(distinct_id) is None, + options=options, ) diff --git a/posthog/ai/gemini/gemini.py b/posthog/ai/gemini/gemini.py index 5c5c8fd60..d0aa8f80c 100644 --- a/posthog/ai/gemini/gemini.py +++ b/posthog/ai/gemini/gemini.py @@ -7,6 +7,7 @@ from ..types import StreamingEventData as StreamingEventData from ..types import TokenUsage from ..utils import ( + _resolve_ai_client, call_llm_and_track_usage, capture_streaming_event as capture_streaming_event, finalize_ai_content as finalize_ai_content, @@ -18,7 +19,6 @@ _GeminiAioNamespace, _GeminiModelsPolicy, _build_gemini_client, - _resolve_posthog_client, ) from .gemini_async import AsyncModels from .gemini_converter import ( @@ -77,6 +77,7 @@ def __init__( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs, ): """ @@ -93,10 +94,12 @@ def __init__( posthog_properties: Default properties for all calls (can be overridden per call) posthog_privacy_mode: Default privacy mode for all calls (a call can enable it, not disable it) posthog_groups: Default groups for all calls (can be overridden per call) + posthog_options: Default capture options for all calls, such as + ``{"cookieless_mode": True}`` (can be overridden per call) **kwargs: Additional arguments (for future compatibility) """ - self._ph_client = _resolve_posthog_client(posthog_client) + self._ph_client = _resolve_ai_client(posthog_client) # Built once here and shared by every surface, so a client that uses both # `models` and `aio.models` still opens a single provider client. @@ -117,6 +120,7 @@ def __init__( posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, + posthog_options=posthog_options, **kwargs, ) self.files = self._provider_client.files @@ -128,6 +132,7 @@ def __init__( posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, + posthog_options=posthog_options, **kwargs, ), files=self._provider_client.aio.files, @@ -156,6 +161,7 @@ def __init__( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, provider_client: Optional[Any] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs, ): """ @@ -174,6 +180,8 @@ def __init__( posthog_groups: Default groups for all calls provider_client: An already-built genai.Client to reuse instead of constructing one from the connection arguments above + posthog_options: Default capture options for all calls, such as + ``{"cookieless_mode": True}`` (can be overridden per call) **kwargs: Additional arguments (for future compatibility) """ @@ -190,6 +198,7 @@ def __init__( posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, + posthog_options=posthog_options, provider_client=provider_client, ) @@ -202,6 +211,7 @@ def generate_content( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -218,6 +228,10 @@ def generate_content( posthog_properties: Extra properties to include in the event (merged with client defaults) posthog_privacy_mode: Whether to redact sensitive information (cannot disable a client default of True) posthog_groups: Group analytics properties (overrides client default) + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``, merged with client defaults. They + win over context options and ``super_options``. An event without + a distinct ID always sends ``process_person_profile: False``. **kwargs: Arguments passed to Gemini's generate_content """ @@ -231,6 +245,7 @@ def generate_content( posthog_groups, ) ) + options = self._merge_posthog_options(posthog_options) kwargs_with_contents = {"model": model, "contents": contents, **kwargs} @@ -244,6 +259,7 @@ def generate_content( groups, self._base_url, self._client.models.generate_content, + posthog_options=options, **kwargs_with_contents, ) @@ -256,6 +272,7 @@ def _generate_content_streaming( properties: Optional[Dict[str, Any]], privacy_mode: bool, groups: Optional[Dict[str, Any]], + options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): start_time = time.time() @@ -284,6 +301,7 @@ def _generate_content_streaming( accumulated_content, stop_reason=stop_reason, error=exc, + options=options, ) except Exception: # Telemetry must never replace the provider's own error, and the @@ -343,6 +361,7 @@ def generator(): accumulated_content, stop_reason=stop_reason, error=stream_error, + options=options, ) return generator() @@ -356,6 +375,7 @@ def generate_content_stream( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -370,6 +390,10 @@ def generate_content_stream( posthog_privacy_mode: Whether to redact captured input and output, overriding the client default. posthog_groups: Optional PostHog groups, overriding the client default. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``, merged with client defaults. They + win over context options and ``super_options``. An event without + a distinct ID always sends ``process_person_profile: False``. **kwargs: Arguments passed to Gemini's ``generate_content_stream`` API. Returns: @@ -385,6 +409,7 @@ def generate_content_stream( posthog_groups, ) ) + options = self._merge_posthog_options(posthog_options) return self._generate_content_streaming( model, @@ -394,6 +419,7 @@ def generate_content_stream( properties, privacy_mode, groups, + options=options, **kwargs, ) @@ -406,6 +432,7 @@ def embed_content( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -419,6 +446,10 @@ def embed_content( posthog_properties: Extra properties to include in the event (merged with client defaults) posthog_privacy_mode: Whether to redact sensitive information (cannot disable a client default of True) posthog_groups: Group analytics properties (overrides client default) + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``, merged with client defaults. They + win over context options and ``super_options``. An event without + a distinct ID always sends ``process_person_profile: False``. **kwargs: Arguments passed to Gemini's embed_content (e.g., config) """ distinct_id, trace_id, properties, privacy_mode, groups = ( @@ -430,6 +461,7 @@ def embed_content( posthog_groups, ) ) + options = self._merge_posthog_options(posthog_options) start_time = time.time() response = None @@ -450,6 +482,7 @@ def embed_content( properties=properties, privacy_mode=privacy_mode, groups=groups, + options=options, response=response, error=error, latency=time.time() - start_time, diff --git a/posthog/ai/gemini/gemini_async.py b/posthog/ai/gemini/gemini_async.py index 7463318ab..3184e4056 100644 --- a/posthog/ai/gemini/gemini_async.py +++ b/posthog/ai/gemini/gemini_async.py @@ -8,6 +8,7 @@ from ..types import StreamingEventData as StreamingEventData from ..types import TokenUsage from ..utils import ( + _resolve_ai_client, call_llm_and_track_usage_async, capture_streaming_event as capture_streaming_event, finalize_ai_content as finalize_ai_content, @@ -19,7 +20,6 @@ _GeminiAioNamespace, _GeminiModelsPolicy, _build_gemini_client, - _resolve_posthog_client, ) from .gemini_converter import ( extract_gemini_content_from_chunk, @@ -72,6 +72,7 @@ def __init__( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs, ): """ @@ -88,10 +89,12 @@ def __init__( posthog_properties: Default properties for all calls (can be overridden per call) posthog_privacy_mode: Default privacy mode for all calls (a call can enable it, not disable it) posthog_groups: Default groups for all calls (can be overridden per call) + posthog_options: Default capture options for all calls, such as + ``{"cookieless_mode": True}`` (can be overridden per call) **kwargs: Additional arguments (for future compatibility) """ - self._ph_client = _resolve_posthog_client(posthog_client) + self._ph_client = _resolve_ai_client(posthog_client) # Built once here and shared by every surface, so `models`, `aio.models` # and `files` all go through a single provider client. @@ -112,6 +115,7 @@ def __init__( posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, + posthog_options=posthog_options, **kwargs, ) self.files = self._provider_client.aio.files @@ -140,6 +144,7 @@ def __init__( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, provider_client: Optional[Any] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs, ): """ @@ -158,6 +163,8 @@ def __init__( posthog_groups: Default groups for all calls provider_client: An already-built genai.Client to reuse instead of constructing one from the connection arguments above + posthog_options: Default capture options for all calls, such as + ``{"cookieless_mode": True}`` (can be overridden per call) **kwargs: Additional arguments (for future compatibility) """ @@ -174,6 +181,7 @@ def __init__( posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, + posthog_options=posthog_options, provider_client=provider_client, ) @@ -186,6 +194,7 @@ async def generate_content( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -202,6 +211,10 @@ async def generate_content( posthog_properties: Extra properties to include in the event (merged with client defaults) posthog_privacy_mode: Whether to redact sensitive information (cannot disable a client default of True) posthog_groups: Group analytics properties (overrides client default) + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``, merged with client defaults. They + win over context options and ``super_options``. An event without + a distinct ID always sends ``process_person_profile: False``. **kwargs: Arguments passed to Gemini's generate_content """ @@ -215,6 +228,7 @@ async def generate_content( posthog_groups, ) ) + options = self._merge_posthog_options(posthog_options) kwargs_with_contents = {"model": model, "contents": contents, **kwargs} @@ -228,6 +242,7 @@ async def generate_content( groups, self._base_url, self._client.aio.models.generate_content, + posthog_options=options, **kwargs_with_contents, ) @@ -240,6 +255,7 @@ async def _generate_content_streaming( properties: Optional[Dict[str, Any]], privacy_mode: bool, groups: Optional[Dict[str, Any]], + options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): start_time = time.time() @@ -268,6 +284,7 @@ async def _generate_content_streaming( accumulated_content, stop_reason=stop_reason, error=exc, + options=options, ) except Exception: # Telemetry must never replace the provider's own error, and the @@ -328,6 +345,7 @@ async def async_generator(): accumulated_content, stop_reason=stop_reason, error=stream_error, + options=options, ) return AsyncStreamWrapper(async_generator(), stream=response) @@ -341,6 +359,7 @@ async def generate_content_stream( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -355,6 +374,10 @@ async def generate_content_stream( posthog_privacy_mode: Whether to redact captured input and output, overriding the client default. posthog_groups: Optional PostHog groups, overriding the client default. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``, merged with client defaults. They + win over context options and ``super_options``. An event without + a distinct ID always sends ``process_person_profile: False``. **kwargs: Arguments passed to Gemini's async ``generate_content_stream`` API. Returns: @@ -370,6 +393,7 @@ async def generate_content_stream( posthog_groups, ) ) + options = self._merge_posthog_options(posthog_options) return await self._generate_content_streaming( model, @@ -379,6 +403,7 @@ async def generate_content_stream( properties, privacy_mode, groups, + options=options, **kwargs, ) @@ -391,6 +416,7 @@ async def embed_content( posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -404,6 +430,10 @@ async def embed_content( posthog_properties: Extra properties to include in the event (merged with client defaults) posthog_privacy_mode: Whether to redact sensitive information (cannot disable a client default of True) posthog_groups: Group analytics properties (overrides client default) + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``, merged with client defaults. They + win over context options and ``super_options``. An event without + a distinct ID always sends ``process_person_profile: False``. **kwargs: Arguments passed to Gemini's embed_content (e.g., config) """ distinct_id, trace_id, properties, privacy_mode, groups = ( @@ -415,6 +445,7 @@ async def embed_content( posthog_groups, ) ) + options = self._merge_posthog_options(posthog_options) start_time = time.time() response = None @@ -435,6 +466,7 @@ async def embed_content( properties=properties, privacy_mode=privacy_mode, groups=groups, + options=options, response=response, error=error, latency=time.time() - start_time, diff --git a/posthog/ai/langchain/callbacks.py b/posthog/ai/langchain/callbacks.py index 27b2eb6aa..0972cf43a 100644 --- a/posthog/ai/langchain/callbacks.py +++ b/posthog/ai/langchain/callbacks.py @@ -39,21 +39,22 @@ ToolMessage, ) from langchain_core.outputs import ChatGeneration, LLMResult -from langchain_core.outputs import Generation as _Generation from pydantic import BaseModel -from posthog import setup from posthog.ai.gateway import warn_if_posthog_ai_gateway from posthog.ai.utils import ( + _ai_event_options, _capture_ai_event, _extract_cache_creation_ttl_breakdown, - _stream_error_event_status, + _resolve_ai_client, + _user_distinct_id, finalize_ai_content, _format_ai_error, get_model_params, _privacy_mode_enabled, _redact_mcp_tool_credentials, _responses_stop_reason, + _stream_error_event_status, with_privacy_mode, ) from posthog.client import Client @@ -93,6 +94,8 @@ class GenerationMetadata(SpanMetadata): """Tools provided to the model.""" posthog_properties: Optional[Dict[str, Any]] = None """PostHog properties of the run.""" + posthog_options: Optional[Dict[str, Any]] = None + """PostHog capture options of the run.""" RunMetadata = Union[SpanMetadata, GenerationMetadata] @@ -122,6 +125,9 @@ class CallbackHandler(BaseCallbackHandler): _properties: Optional[Dict[str, Any]] """Global properties to be sent with every event.""" + _options: Dict[str, Any] + """Global capture options to be sent with every event.""" + _runs: RunMetadataStorage """Mapping of run IDs to run metadata as run metadata is only available on the start of generation.""" @@ -140,6 +146,7 @@ def __init__( properties: Optional[Dict[str, Any]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, + options: Optional[Dict[str, Any]] = None, ): """ Args: @@ -149,13 +156,19 @@ def __init__( properties: Optional additional metadata to use for the trace. privacy_mode: Whether to redact the input and output of the trace. groups: Optional additional PostHog groups to use for the trace. + options: Optional capture options for every event of the trace, such + as ``{"cookieless_mode": True}``. They win over a run's + ``posthog_options`` metadata, context options and + ``super_options``. An event without a distinct ID always sends + ``process_person_profile: False``. """ - self._ph_client = client or setup() + self._ph_client = _resolve_ai_client(client) self._distinct_id = distinct_id self._trace_id = trace_id self._properties = properties or {} self._privacy_mode = privacy_mode self._groups = groups or {} + self._options = _ai_event_options(options) self._runs = {} self._parent_tree = {} @@ -480,6 +493,7 @@ def _set_llm_metadata( generation.provider = provider generation.posthog_properties = metadata.get("posthog_properties") + generation.posthog_options = metadata.get("posthog_options") try: base_url = serialized["kwargs"]["openai_api_base"] if base_url is not None: @@ -570,7 +584,7 @@ def _capture_trace_or_span( ) event_properties["$ai_is_error"] = True event_properties = self._capture_exception_and_update_properties( - outputs, event_properties + outputs, event_properties, self._options ) elif outputs is not None: @@ -580,19 +594,21 @@ def _capture_trace_or_span( finalize_ai_content(outputs, self._ph_client), ) - if self._distinct_id is None: - event_properties["$process_person_profile"] = False - _capture_ai_event( self._ph_client, event_name, - distinct_id=self._distinct_id or run_id, + distinct_id=_user_distinct_id(self._distinct_id) or run_id, properties=event_properties, groups=self._groups, + personless=_user_distinct_id(self._distinct_id) is None, + options=self._options, ) def _capture_exception_and_update_properties( - self, exception: BaseException, event_properties: Dict[str, Any] + self, + exception: BaseException, + event_properties: Dict[str, Any], + options: Dict[str, Any], ) -> Dict[str, Any]: # An `$exception` event carries the message and stack, which echo prompts and output. if not getattr( @@ -600,11 +616,16 @@ def _capture_exception_and_update_properties( ) or _privacy_mode_enabled(self._ph_client, self._privacy_mode): return event_properties + exception_options = dict(options) + if _user_distinct_id(self._distinct_id) is None: + # Matches the AI event: without a user, person processing stays off. + exception_options["process_person_profile"] = False exception_id = self._ph_client.capture_exception( exception, distinct_id=self._distinct_id, groups=self._groups, properties=event_properties, + options=exception_options or None, ) if exception_id: event_properties["$exception_event_id"] = exception_id @@ -643,7 +664,33 @@ def _capture_generation( parent_run_id: Optional[UUID] = None, include_parent_id: bool = True, ): - event_properties = self._generation_properties(trace_id, run_id, run, output) + # The served tier comes from the response, because a requested tier can be refused. + model_params = run.model_params + served_tier = None + if isinstance(output, LLMResult) and isinstance(output.llm_output, dict): + served_tier = output.llm_output.get("service_tier") + if served_tier is not None: + model_params = {**(model_params or {}), "service_tier": served_tier} + + event_properties = { + "$ai_trace_id": trace_id, + "$ai_span_id": run_id, + "$ai_span_name": run.name, + "$ai_provider": run.provider, + "$ai_model": run.model, + "$ai_model_parameters": model_params, + # The explicit served-tier signal cost processing prices from. + **({"$ai_service_tier": served_tier} if served_tier is not None else {}), + "$ai_input": with_privacy_mode( + self._ph_client, + self._privacy_mode, + finalize_ai_content(run.input, self._ph_client), + ), + "$ai_http_status": 200, + "$ai_latency": run.latency, + "$ai_base_url": run.base_url, + "$ai_framework": "langchain", + } if include_parent_id: event_properties["$ai_parent_id"] = parent_run_id @@ -658,9 +705,6 @@ def _capture_generation( if self._properties: event_properties.update(self._properties) - if self._distinct_id is None: - event_properties["$process_person_profile"] = False - if isinstance(output, BaseException): event_properties["$ai_http_status"] = _get_http_status(output) event_properties["$ai_error"] = _format_ai_error( @@ -669,85 +713,78 @@ def _capture_generation( event_properties["$ai_is_error"] = True event_properties = self._capture_exception_and_update_properties( - output, event_properties + output, + event_properties, + # The handler's options win over the run's, like its properties. + {**_ai_event_options(run.posthog_options), **self._options}, ) else: - _add_generation_usage( - event_properties, _parse_usage(output, run.provider, run.model) + # Add usage + usage = _parse_usage(output, run.provider, run.model) + # Omitted when the provider never reported a count: absent means + # unknown, 0 is a report of nothing. + if usage.input_tokens is not None: + event_properties["$ai_input_tokens"] = usage.input_tokens + if usage.output_tokens is not None: + event_properties["$ai_output_tokens"] = usage.output_tokens + if usage.cache_write_tokens is not None: + event_properties["$ai_cache_creation_input_tokens"] = ( + usage.cache_write_tokens + ) + if ( + usage.cache_write_5m_tokens is not None + and usage.cache_write_1h_tokens is not None + ): + event_properties["$ai_cache_creation_5m_input_tokens"] = ( + usage.cache_write_5m_tokens + ) + event_properties["$ai_cache_creation_1h_input_tokens"] = ( + usage.cache_write_1h_tokens + ) + if usage.cache_read_tokens is not None: + event_properties["$ai_cache_read_input_tokens"] = ( + usage.cache_read_tokens + ) + if usage.reasoning_tokens is not None: + event_properties["$ai_reasoning_tokens"] = usage.reasoning_tokens + if usage.web_search_count is not None and usage.web_search_count > 0: + event_properties["$ai_web_search_count"] = usage.web_search_count + + # Generation results + generation_result = output.generations[-1] + if isinstance(generation_result[-1], ChatGeneration): + completions = [ + _convert_message_to_dict(cast(ChatGeneration, generation).message) + for generation in generation_result + ] + else: + completions = [ + _extract_raw_response(generation) + for generation in generation_result + ] + event_properties["$ai_output_choices"] = with_privacy_mode( + self._ph_client, + self._privacy_mode, + finalize_ai_content(completions, self._ph_client), ) - self._add_generation_output(event_properties, output) + # Extract the stop reason from the generation and its metadata + if output.generations and output.generations[-1]: + stop_reason = _extract_stop_reason(output.generations[-1][-1]) + if stop_reason is not None: + event_properties["$ai_stop_reason"] = stop_reason _capture_ai_event( self._ph_client, "$ai_generation", - distinct_id=self._distinct_id or trace_id, + distinct_id=_user_distinct_id(self._distinct_id) or trace_id, properties=event_properties, groups=self._groups, + personless=_user_distinct_id(self._distinct_id) is None, + # The handler's options win over the run's, like its properties. + options={**_ai_event_options(run.posthog_options), **self._options}, ) - def _generation_properties( - self, - trace_id: Any, - run_id: UUID, - run: GenerationMetadata, - output: Union[LLMResult, BaseException], - ) -> dict[str, Any]: - # The served tier comes from the response, because a requested tier can be refused. - model_params = run.model_params - served_tier = None - if isinstance(output, LLMResult) and isinstance(output.llm_output, dict): - served_tier = output.llm_output.get("service_tier") - if served_tier is not None: - model_params = {**(model_params or {}), "service_tier": served_tier} - - event_properties = { - "$ai_trace_id": trace_id, - "$ai_span_id": run_id, - "$ai_span_name": run.name, - "$ai_provider": run.provider, - "$ai_model": run.model, - "$ai_model_parameters": model_params, - # The explicit served-tier signal cost processing prices from. - **({"$ai_service_tier": served_tier} if served_tier is not None else {}), - "$ai_input": with_privacy_mode( - self._ph_client, - self._privacy_mode, - finalize_ai_content(run.input, self._ph_client), - ), - "$ai_http_status": 200, - "$ai_latency": run.latency, - "$ai_base_url": run.base_url, - "$ai_framework": "langchain", - } - return event_properties - - def _add_generation_output( - self, event_properties: dict[str, Any], output: LLMResult - ) -> None: - # Generation results - generation_result = output.generations[-1] - if isinstance(generation_result[-1], ChatGeneration): - completions = [ - _convert_message_to_dict(cast(ChatGeneration, generation).message) - for generation in generation_result - ] - else: - completions = [ - _extract_raw_response(generation) for generation in generation_result - ] - event_properties["$ai_output_choices"] = with_privacy_mode( - self._ph_client, - self._privacy_mode, - finalize_ai_content(completions, self._ph_client), - ) - - # Extract the stop reason from the generation and its metadata - if output.generations and output.generations[-1]: - stop_reason = _extract_stop_reason(output.generations[-1][-1]) - if stop_reason is not None: - event_properties["$ai_stop_reason"] = stop_reason - def _log_debug_event( self, event_name: str, @@ -811,18 +848,6 @@ def _convert_lc_tool_calls_to_oai( def _convert_message_to_dict(message: BaseMessage) -> dict[str, Any]: - message_dict = _message_role_and_content(message) - - if message.additional_kwargs: - message_dict.update(message.additional_kwargs) - - if "content" in message_dict and not message_dict["content"]: - message_dict["content"] = "" - - return message_dict - - -def _message_role_and_content(message: BaseMessage) -> dict[str, Any]: # assistant message if isinstance(message, HumanMessage): message_dict = {"role": "user", "content": message.content} @@ -841,6 +866,12 @@ def _message_role_and_content(message: BaseMessage) -> dict[str, Any]: else: message_dict = {"role": message.type, "content": str(message.content)} + if message.additional_kwargs: + message_dict.update(message.additional_kwargs) + + if "content" in message_dict and not message_dict["content"]: + message_dict["content"] = "" + return message_dict @@ -880,9 +911,63 @@ def _parse_usage_model( if isinstance(usage, BaseModel): usage = usage.__dict__ - parsed_usage = _flat_usage_counts(usage) + conversion_list = [ + # https://pypi.org/project/langchain-anthropic/ (works also for Bedrock-Anthropic) + ("input_tokens", "input"), + ("output_tokens", "output"), + ("cache_creation_input_tokens", "cache_write"), + ("cache_read_input_tokens", "cache_read"), + # https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/get-token-count + ("prompt_token_count", "input"), + ("candidates_token_count", "output"), + ("cached_content_token_count", "cache_read"), + ("thoughts_token_count", "reasoning"), + # Bedrock: https://docs.aws.amazon.com/bedrock/latest/userguide/monitoring-cw.html#runtime-cloudwatch-metrics + ("inputTokenCount", "input"), + ("outputTokenCount", "output"), + ("cacheCreationInputTokenCount", "cache_write"), + ("cacheReadInputTokenCount", "cache_read"), + # Bedrock Anthropic + ("prompt_tokens", "input"), + ("completion_tokens", "output"), + ("cache_creation_input_tokens", "cache_write"), + ("cache_read_input_tokens", "cache_read"), + # langchain-ibm https://pypi.org/project/langchain-ibm/ + ("input_token_count", "input"), + ("generated_token_count", "output"), + ] + + parsed_usage = {} + for model_key, type_key in conversion_list: + if model_key in usage: + captured_count = usage[model_key] + final_count = ( + sum(captured_count) + if isinstance(captured_count, list) + else captured_count + ) # For Bedrock, the token count is a list when streamed + + parsed_usage[type_key] = final_count - _add_usage_details(parsed_usage, usage) + # Caching (OpenAI & langchain 0.3.9+) + if "input_token_details" in usage and isinstance( + usage["input_token_details"], dict + ): + input_token_details = usage["input_token_details"] + parsed_usage["cache_write"] = input_token_details.get("cache_creation") + cache_write_ttl = _extract_cache_creation_ttl_breakdown(input_token_details) + if cache_write_ttl is not None: + cache_write_5m, cache_write_1h = cache_write_ttl + parsed_usage["cache_write_5m"] = cache_write_5m + parsed_usage["cache_write_1h"] = cache_write_1h + parsed_usage["cache_write"] = cache_write_5m + cache_write_1h + parsed_usage["cache_read"] = input_token_details.get("cache_read") + + # Reasoning (OpenAI & langchain 0.3.9+) + if "output_token_details" in usage and isinstance( + usage["output_token_details"], dict + ): + parsed_usage["reasoning"] = usage["output_token_details"].get("reasoning") # Anthropic reports the exact number of web searches of a response web_search_requests = _extract_web_search_requests(usage) @@ -905,13 +990,6 @@ def _parse_usage_model( cache_write_1h_tokens=parsed_usage.get("cache_write_1h"), web_search_count=parsed_usage.get("web_search"), ) - _subtract_anthropic_cache(normalized_usage, provider, model) - return normalized_usage - - -def _subtract_anthropic_cache( - normalized_usage: ModelUsage, provider: Optional[str], model: Optional[str] -) -> None: # For Anthropic providers, LangChain reports input_tokens as the sum of all input tokens. # Our cost calculation expects them to be separate for Anthropic, so we subtract cache tokens. # Both cache_read and cache_write tokens should be subtracted since Anthropic's raw API @@ -919,7 +997,11 @@ def _subtract_anthropic_cache( # For other providers (OpenAI, etc.), input_tokens already excludes cache tokens as expected. # Match logic consistent with plugin-server: exact match on provider, substring # match on model, or a Claude model under another provider (e.g. Vertex AI) - is_anthropic = _is_anthropic_model(provider, model) + is_anthropic = False + if provider and provider.lower() == "anthropic": + is_anthropic = True + elif model and ("anthropic" in model.lower() or model.lower().startswith("claude")): + is_anthropic = True if is_anthropic and normalized_usage.input_tokens: cache_tokens = (normalized_usage.cache_read_tokens or 0) + ( @@ -929,70 +1011,7 @@ def _subtract_anthropic_cache( normalized_usage.input_tokens = max( normalized_usage.input_tokens - cache_tokens, 0 ) - - -def _add_usage_details(parsed_usage: dict, usage: dict) -> None: - # Caching (OpenAI & langchain 0.3.9+) - if "input_token_details" in usage and isinstance( - usage["input_token_details"], dict - ): - input_token_details = usage["input_token_details"] - parsed_usage["cache_write"] = input_token_details.get("cache_creation") - cache_write_ttl = _extract_cache_creation_ttl_breakdown(input_token_details) - if cache_write_ttl is not None: - cache_write_5m, cache_write_1h = cache_write_ttl - parsed_usage["cache_write_5m"] = cache_write_5m - parsed_usage["cache_write_1h"] = cache_write_1h - parsed_usage["cache_write"] = cache_write_5m + cache_write_1h - parsed_usage["cache_read"] = input_token_details.get("cache_read") - - # Reasoning (OpenAI & langchain 0.3.9+) - if "output_token_details" in usage and isinstance( - usage["output_token_details"], dict - ): - parsed_usage["reasoning"] = usage["output_token_details"].get("reasoning") - - -def _flat_usage_counts(usage: dict) -> dict: - conversion_list = [ - # https://pypi.org/project/langchain-anthropic/ (works also for Bedrock-Anthropic) - ("input_tokens", "input"), - ("output_tokens", "output"), - ("cache_creation_input_tokens", "cache_write"), - ("cache_read_input_tokens", "cache_read"), - # https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/get-token-count - ("prompt_token_count", "input"), - ("candidates_token_count", "output"), - ("cached_content_token_count", "cache_read"), - ("thoughts_token_count", "reasoning"), - # Bedrock: https://docs.aws.amazon.com/bedrock/latest/userguide/monitoring-cw.html#runtime-cloudwatch-metrics - ("inputTokenCount", "input"), - ("outputTokenCount", "output"), - ("cacheCreationInputTokenCount", "cache_write"), - ("cacheReadInputTokenCount", "cache_read"), - # Bedrock Anthropic - ("prompt_tokens", "input"), - ("completion_tokens", "output"), - ("cache_creation_input_tokens", "cache_write"), - ("cache_read_input_tokens", "cache_read"), - # langchain-ibm https://pypi.org/project/langchain-ibm/ - ("input_token_count", "input"), - ("generated_token_count", "output"), - ] - - parsed_usage = {} - for model_key, type_key in conversion_list: - if model_key in usage: - captured_count = usage[model_key] - final_count = ( - sum(captured_count) - if isinstance(captured_count, list) - else captured_count - ) # For Bedrock, the token count is a list when streamed - - parsed_usage[type_key] = final_count - - return parsed_usage + return normalized_usage def _parse_usage( @@ -1029,9 +1048,45 @@ def _parse_usage( llm_usage = _parse_usage_model(generation["usage"], provider, model) break - parsed = _generation_usage(generation, provider, model) - if parsed is not None: - llm_usage = parsed + for generation_chunk in generation: + if generation_chunk.generation_info and ( + "usage_metadata" in generation_chunk.generation_info + ): + llm_usage = _parse_usage_model( + generation_chunk.generation_info["usage_metadata"], + provider, + model, + ) + break + + message_chunk = getattr(generation_chunk, "message", {}) + response_metadata = getattr(message_chunk, "response_metadata", {}) + + bedrock_anthropic_usage = ( + response_metadata.get("usage", None) # for Bedrock-Anthropic + if isinstance(response_metadata, dict) + else None + ) + bedrock_titan_usage = ( + response_metadata.get( + "amazon-bedrock-invocationMetrics", None + ) # for Bedrock-Titan + if isinstance(response_metadata, dict) + else None + ) + # LangChain's standard usage, which also covers Ollama + usage_metadata = getattr(message_chunk, "usage_metadata", None) + + # Prefer the standard usage: its input_tokens include cache reads + # and writes, as the Anthropic subtraction in _parse_usage_model + # expects. ChatAnthropic also copies the raw API usage, whose + # input_tokens already exclude the cache, into response_metadata. + chunk_usage = ( + usage_metadata or bedrock_anthropic_usage or bedrock_titan_usage + ) + if chunk_usage: + llm_usage = _parse_usage_model(chunk_usage, provider, model) + break if llm_usage.web_search_count is None: llm_usage.web_search_count = web_search_count @@ -1091,88 +1146,3 @@ def _stringify_exception(exception: BaseException) -> str: if description: return f"{exception.__class__.__name__}: {description}" return exception.__class__.__name__ - - -def _add_generation_usage( - event_properties: dict[str, Any], usage: "ModelUsage" -) -> None: - # Omitted when the provider never reported a count: absent means unknown, - # 0 is a report of nothing. - for field, property_name in ( - ("input_tokens", "$ai_input_tokens"), - ("output_tokens", "$ai_output_tokens"), - ("cache_write_tokens", "$ai_cache_creation_input_tokens"), - ): - value = getattr(usage, field) - if value is not None: - event_properties[property_name] = value - if ( - usage.cache_write_5m_tokens is not None - and usage.cache_write_1h_tokens is not None - ): - event_properties["$ai_cache_creation_5m_input_tokens"] = ( - usage.cache_write_5m_tokens - ) - event_properties["$ai_cache_creation_1h_input_tokens"] = ( - usage.cache_write_1h_tokens - ) - for field, property_name in ( - ("cache_read_tokens", "$ai_cache_read_input_tokens"), - ("reasoning_tokens", "$ai_reasoning_tokens"), - ): - value = getattr(usage, field) - if value is not None: - event_properties[property_name] = value - if usage.web_search_count is not None and usage.web_search_count > 0: - event_properties["$ai_web_search_count"] = usage.web_search_count - - -def _generation_usage( - generation: list[_Generation], provider: Optional[str], model: Optional[str] -) -> Optional[ModelUsage]: - for generation_chunk in generation: - if generation_chunk.generation_info and ( - "usage_metadata" in generation_chunk.generation_info - ): - return _parse_usage_model( - generation_chunk.generation_info["usage_metadata"], - provider, - model, - ) - - message_chunk = getattr(generation_chunk, "message", {}) - response_metadata = getattr(message_chunk, "response_metadata", {}) - - bedrock_anthropic_usage = ( - response_metadata.get("usage", None) # for Bedrock-Anthropic - if isinstance(response_metadata, dict) - else None - ) - bedrock_titan_usage = ( - response_metadata.get( - "amazon-bedrock-invocationMetrics", None - ) # for Bedrock-Titan - if isinstance(response_metadata, dict) - else None - ) - # LangChain's standard usage, which also covers Ollama - usage_metadata = getattr(message_chunk, "usage_metadata", None) - - # Prefer the standard usage: its input_tokens include cache reads - # and writes, as the Anthropic subtraction in _parse_usage_model - # expects. ChatAnthropic also copies the raw API usage, whose - # input_tokens already exclude the cache, into response_metadata. - chunk_usage = usage_metadata or bedrock_anthropic_usage or bedrock_titan_usage - if chunk_usage: - return _parse_usage_model(chunk_usage, provider, model) - return None - - -def _is_anthropic_model(provider: Optional[str], model: Optional[str]) -> bool: - is_anthropic = False - if provider and provider.lower() == "anthropic": - is_anthropic = True - elif model and ("anthropic" in model.lower() or model.lower().startswith("claude")): - is_anthropic = True - - return is_anthropic diff --git a/posthog/ai/langchain/middleware.py b/posthog/ai/langchain/middleware.py index e434c8473..669a2d010 100644 --- a/posthog/ai/langchain/middleware.py +++ b/posthog/ai/langchain/middleware.py @@ -59,7 +59,14 @@ def __init__( properties: Optional[dict[str, Any]] = None, privacy_mode: bool = False, groups: Optional[dict[str, Any]] = None, + options: Optional[dict[str, Any]] = None, ) -> None: + """ + Args: + options: Optional capture options for every event, such as + ``{"cookieless_mode": True}``. The other arguments are the same + as :class:`CallbackHandler`'s. + """ self._callback = CallbackHandler( client, distinct_id=distinct_id, @@ -67,6 +74,7 @@ def __init__( properties=properties, privacy_mode=privacy_mode, groups=groups, + options=options, ) def before_agent( diff --git a/posthog/ai/openai/_embeddings.py b/posthog/ai/openai/_embeddings.py index b34c0c358..70a47037a 100644 --- a/posthog/ai/openai/_embeddings.py +++ b/posthog/ai/openai/_embeddings.py @@ -4,6 +4,7 @@ _capture_ai_event, _format_ai_error, _get_http_status, + _user_distinct_id, finalize_ai_content, with_privacy_mode, ) @@ -22,6 +23,7 @@ def _capture_embedding_event( privacy_mode: bool, groups: Optional[Dict[str, Any]], error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ) -> None: """Build and capture telemetry shared by sync and async embedding wrappers.""" usage = getattr(response, "usage", None) @@ -53,14 +55,13 @@ def _capture_embedding_event( ), } - if distinct_id is None: - event_properties["$process_person_profile"] = False - - if hasattr(posthog_client, "capture"): + if callable(getattr(posthog_client, "capture_ai", None)): _capture_ai_event( posthog_client, "$ai_embedding", - distinct_id=distinct_id or trace_id, + distinct_id=_user_distinct_id(distinct_id) or trace_id, properties=event_properties, groups=groups, + personless=_user_distinct_id(distinct_id) is None, + options=options, ) diff --git a/posthog/ai/openai/_streaming.py b/posthog/ai/openai/_streaming.py index 49234bee0..ba8778527 100644 --- a/posthog/ai/openai/_streaming.py +++ b/posthog/ai/openai/_streaming.py @@ -153,6 +153,7 @@ def _build_streaming_event_data( stop_reason: Optional[str], service_tier: Optional[str] = None, error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ) -> StreamingEventData: """Build the fields shared by both OpenAI streaming endpoint events.""" @@ -173,4 +174,5 @@ def _build_streaming_event_data( stop_reason=stop_reason, service_tier=service_tier, error=error, + options=options, ) diff --git a/posthog/ai/openai/openai.py b/posthog/ai/openai/openai.py index e00a2d3c0..b1b71301a 100644 --- a/posthog/ai/openai/openai.py +++ b/posthog/ai/openai/openai.py @@ -13,6 +13,7 @@ ) from posthog.ai.utils import ( + _resolve_ai_client, call_llm_and_track_usage, extract_available_tool_calls as extract_available_tool_calls, finalize_ai_content as finalize_ai_content, @@ -28,7 +29,6 @@ format_openai_streaming_output as _format_openai_streaming_output, ) from posthog.client import Client as PostHogClient -from posthog import setup from posthog.ai.openai._streaming import ( _ChatCompletionsStreamState, _ResponsesStreamState, @@ -68,7 +68,7 @@ def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs): """ super().__init__(**kwargs) - self._ph_client = posthog_client or setup() + self._ph_client = _resolve_ai_client(posthog_client) _wrap_openai_resources(self, _SYNC_RESOURCE_WRAPPERS) @@ -81,6 +81,7 @@ def _parse_and_track( posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): return call_llm_and_track_usage( @@ -93,6 +94,7 @@ def _parse_and_track( posthog_groups, wrapper._client.base_url, wrapper._original.parse, + posthog_options=posthog_options, **kwargs, ) @@ -108,6 +110,7 @@ def create( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -124,6 +127,10 @@ def create( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to OpenAI's ``responses.create`` API. Returns: @@ -143,6 +150,7 @@ def create( posthog_properties, posthog_privacy_mode, posthog_groups, + posthog_options=posthog_options, **kwargs, ) @@ -156,6 +164,7 @@ def create( posthog_groups, self._client.base_url, self._original.create, + posthog_options=posthog_options, **kwargs, ) @@ -166,6 +175,7 @@ def _create_streaming( posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): start_time = time.time() @@ -184,6 +194,7 @@ def _create_streaming( state, time.time() - start_time, error=exc, + options=posthog_options, ) except Exception: # Telemetry must never replace the provider's own error, and the @@ -211,6 +222,7 @@ def generator(): state, time.time() - start_time, error=stream_error, + options=posthog_options, ) return _StreamWrapper(generator(), stream=response) @@ -226,6 +238,7 @@ def _capture_streaming_event( state: _ResponsesStreamState, latency: float, error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ): from posthog.ai.utils import capture_streaming_event @@ -245,6 +258,7 @@ def _capture_streaming_event( stop_reason=state.stop_reason, service_tier=state.service_tier, error=error, + options=options, ) capture_streaming_event(self._client._ph_client, event_data) @@ -256,6 +270,7 @@ def parse( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -272,6 +287,10 @@ def parse( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Any additional parameters for the OpenAI Responses Parse API. Returns: @@ -285,6 +304,7 @@ def parse( posthog_privacy_mode, posthog_groups, posthog_provider_override, + posthog_options=posthog_options, **kwargs, ) @@ -309,6 +329,7 @@ def parse( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -325,6 +346,10 @@ def parse( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to OpenAI's ``chat.completions.parse`` API. Returns: @@ -338,6 +363,7 @@ def parse( posthog_privacy_mode, posthog_groups, posthog_provider_override, + posthog_options=posthog_options, **kwargs, ) @@ -349,6 +375,7 @@ def create( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -365,6 +392,10 @@ def create( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to OpenAI's ``chat.completions.create`` API. Returns: @@ -384,6 +415,7 @@ def create( posthog_properties, posthog_privacy_mode, posthog_groups, + posthog_options=posthog_options, **kwargs, ) @@ -397,6 +429,7 @@ def create( posthog_groups, self._client.base_url, self._original.create, + posthog_options=posthog_options, **kwargs, ) @@ -407,6 +440,7 @@ def _create_streaming( posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): start_time = time.time() @@ -431,6 +465,7 @@ def _create_streaming( state, time.time() - start_time, error=exc, + options=posthog_options, ) except Exception: # Telemetry must never replace the provider's own error, and the @@ -458,6 +493,7 @@ def generator(): state, time.time() - start_time, error=stream_error, + options=posthog_options, ) return _StreamWrapper(generator(), stream=response) @@ -473,6 +509,7 @@ def _capture_streaming_event( state: _ChatCompletionsStreamState, latency: float, error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ): from posthog.ai.utils import capture_streaming_event @@ -492,6 +529,7 @@ def _capture_streaming_event( stop_reason=state.stop_reason, service_tier=state.service_tier, error=error, + options=options, ) capture_streaming_event(self._client._ph_client, event_data) @@ -507,6 +545,7 @@ def create( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -523,6 +562,10 @@ def create( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Any additional parameters for the OpenAI Embeddings API. Returns: @@ -552,6 +595,7 @@ def create( privacy_mode=posthog_privacy_mode, groups=posthog_groups, error=exc, + options=posthog_options, ) raise end_time = time.time() @@ -567,6 +611,7 @@ def create( properties=posthog_properties, privacy_mode=posthog_privacy_mode, groups=posthog_groups, + options=posthog_options, ) return response @@ -600,6 +645,7 @@ def parse( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -616,6 +662,10 @@ def parse( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to OpenAI's beta ``chat.completions.parse`` API. Returns: @@ -629,6 +679,7 @@ def parse( posthog_privacy_mode, posthog_groups, posthog_provider_override, + posthog_options=posthog_options, **kwargs, ) diff --git a/posthog/ai/openai/openai_async.py b/posthog/ai/openai/openai_async.py index 3d105f7a2..9d59dfcfc 100644 --- a/posthog/ai/openai/openai_async.py +++ b/posthog/ai/openai/openai_async.py @@ -13,8 +13,8 @@ "Please install the OpenAI SDK to use this feature: 'pip install openai'" ) -from posthog import setup from posthog.ai.utils import ( + _resolve_ai_client, call_llm_and_track_usage_async, extract_available_tool_calls as extract_available_tool_calls, finalize_ai_content as finalize_ai_content, @@ -69,7 +69,7 @@ def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs): """ super().__init__(**kwargs) - self._ph_client = posthog_client or setup() + self._ph_client = _resolve_ai_client(posthog_client) _wrap_openai_resources(self, _ASYNC_RESOURCE_WRAPPERS) @@ -82,6 +82,7 @@ async def _parse_and_track( posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): return await call_llm_and_track_usage_async( @@ -94,6 +95,7 @@ async def _parse_and_track( posthog_groups, wrapper._client.base_url, wrapper._original.parse, + posthog_options=posthog_options, **kwargs, ) @@ -109,6 +111,7 @@ async def create( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -125,6 +128,10 @@ async def create( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to OpenAI's async ``responses.create`` API. Returns: @@ -144,6 +151,7 @@ async def create( posthog_properties, posthog_privacy_mode, posthog_groups, + posthog_options=posthog_options, **kwargs, ) @@ -157,6 +165,7 @@ async def create( posthog_groups, self._client.base_url, self._original.create, + posthog_options=posthog_options, **kwargs, ) @@ -167,6 +176,7 @@ async def _create_streaming( posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): start_time = time.time() @@ -185,6 +195,7 @@ async def _create_streaming( state, time.time() - start_time, error=exc, + options=posthog_options, ) except Exception: # Telemetry must never replace the provider's own error, and the @@ -212,6 +223,7 @@ async def async_generator(): state, time.time() - start_time, error=stream_error, + options=posthog_options, ) return AsyncStreamWrapper(async_generator(), stream=response) @@ -227,6 +239,7 @@ async def _capture_streaming_event( state: _ResponsesStreamState, latency: float, error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ): from posthog.ai.utils import capture_streaming_event @@ -246,6 +259,7 @@ async def _capture_streaming_event( stop_reason=state.stop_reason, service_tier=state.service_tier, error=error, + options=options, ) capture_streaming_event(self._client._ph_client, event_data) @@ -257,6 +271,7 @@ async def parse( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -273,6 +288,10 @@ async def parse( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Any additional parameters for the OpenAI Responses Parse API. Returns: @@ -286,6 +305,7 @@ async def parse( posthog_privacy_mode, posthog_groups, posthog_provider_override, + posthog_options=posthog_options, **kwargs, ) @@ -310,6 +330,7 @@ async def parse( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -326,6 +347,10 @@ async def parse( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to OpenAI's async ``chat.completions.parse`` API. Returns: @@ -339,6 +364,7 @@ async def parse( posthog_privacy_mode, posthog_groups, posthog_provider_override, + posthog_options=posthog_options, **kwargs, ) @@ -350,6 +376,7 @@ async def create( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -366,6 +393,10 @@ async def create( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to OpenAI's async ``chat.completions.create`` API. Returns: @@ -386,6 +417,7 @@ async def create( posthog_properties, posthog_privacy_mode, posthog_groups, + posthog_options=posthog_options, **kwargs, ) @@ -399,6 +431,7 @@ async def create( posthog_groups, self._client.base_url, self._original.create, + posthog_options=posthog_options, **kwargs, ) return response @@ -410,6 +443,7 @@ async def _create_streaming( posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): start_time = time.time() @@ -435,6 +469,7 @@ async def _create_streaming( state, time.time() - start_time, error=exc, + options=posthog_options, ) except Exception: # Telemetry must never replace the provider's own error, and the @@ -462,6 +497,7 @@ async def async_generator(): state, time.time() - start_time, error=stream_error, + options=posthog_options, ) return AsyncStreamWrapper(async_generator(), stream=response) @@ -477,6 +513,7 @@ async def _capture_streaming_event( state: _ChatCompletionsStreamState, latency: float, error: Optional[BaseException] = None, + options: Optional[Dict[str, Any]] = None, ): from posthog.ai.utils import capture_streaming_event @@ -496,6 +533,7 @@ async def _capture_streaming_event( stop_reason=state.stop_reason, service_tier=state.service_tier, error=error, + options=options, ) capture_streaming_event(self._client._ph_client, event_data) @@ -511,6 +549,7 @@ async def create( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -527,6 +566,10 @@ async def create( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Any additional parameters for the OpenAI Embeddings API. Returns: @@ -556,6 +599,7 @@ async def create( privacy_mode=posthog_privacy_mode, groups=posthog_groups, error=exc, + options=posthog_options, ) raise end_time = time.time() @@ -571,6 +615,7 @@ async def create( properties=posthog_properties, privacy_mode=posthog_privacy_mode, groups=posthog_groups, + options=posthog_options, ) return response @@ -604,6 +649,7 @@ async def parse( posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ): """ @@ -620,6 +666,10 @@ async def parse( an OpenAI-compatible endpoint (e.g. DeepSeek, Groq) via a custom ``base_url``, so cost attribution matches the real provider. Defaults to ``"openai"`` when omitted. + posthog_options: Capture options for the event, such as + ``{"cookieless_mode": True}``. They win over context options + and ``super_options``. An event without a distinct ID always + sends ``process_person_profile: False``. **kwargs: Arguments passed to OpenAI's async beta ``chat.completions.parse`` API. Returns: @@ -633,6 +683,7 @@ async def parse( posthog_privacy_mode, posthog_groups, posthog_provider_override, + posthog_options=posthog_options, **kwargs, ) diff --git a/posthog/ai/openai/openai_providers.py b/posthog/ai/openai/openai_providers.py index 7c0ce04b6..1661903b8 100644 --- a/posthog/ai/openai/openai_providers.py +++ b/posthog/ai/openai/openai_providers.py @@ -23,8 +23,8 @@ ) from .wrapper_utils import _wrap_openai_resources +from posthog.ai.utils import _resolve_ai_client from posthog.client import Client as PostHogClient -from posthog import setup class AzureOpenAI(openai.AzureOpenAI): @@ -49,7 +49,7 @@ def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs): ``api_key``, ``azure_endpoint``, or ``api_version``. """ super().__init__(**kwargs) - self._ph_client = posthog_client or setup() + self._ph_client = _resolve_ai_client(posthog_client) _wrap_openai_resources(self, _SYNC_RESOURCE_WRAPPERS) @@ -76,6 +76,6 @@ def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs): ``api_key``, ``azure_endpoint``, or ``api_version``. """ super().__init__(**kwargs) - self._ph_client = posthog_client or setup() + self._ph_client = _resolve_ai_client(posthog_client) _wrap_openai_resources(self, _ASYNC_RESOURCE_WRAPPERS) diff --git a/posthog/ai/openai_agents/__init__.py b/posthog/ai/openai_agents/__init__.py index 2e1611cc7..d440f33e8 100644 --- a/posthog/ai/openai_agents/__init__.py +++ b/posthog/ai/openai_agents/__init__.py @@ -25,6 +25,7 @@ def instrument( privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None, + options: Optional[Dict[str, Any]] = None, ) -> PostHogTracingProcessor: """ One-liner to instrument OpenAI Agents SDK with PostHog tracing. @@ -39,6 +40,10 @@ def instrument( privacy_mode: If True, redacts input/output content from events. groups: Optional PostHog groups to associate with events. properties: Optional additional properties to include with all events. + options: Optional capture options for all events, such as + ``{"cookieless_mode": True}``. They win over context options and + ``super_options``. An event without a distinct ID always sends + ``process_person_profile: False``. Returns: PostHogTracingProcessor: The registered processor instance. @@ -71,6 +76,7 @@ def instrument( privacy_mode=privacy_mode, groups=groups, properties=properties, + options=options, ) add_trace_processor(processor) return processor diff --git a/posthog/ai/openai_agents/processor.py b/posthog/ai/openai_agents/processor.py index 5dd8ed40a..8b62285e4 100644 --- a/posthog/ai/openai_agents/processor.py +++ b/posthog/ai/openai_agents/processor.py @@ -19,11 +19,13 @@ TranscriptionSpanData, ) -from posthog import setup from posthog.ai.media import ensure_serializable as _ensure_serializable from posthog.ai.sanitization import _full_ai_capture_enabled, _placeholder from posthog.ai.utils import ( + _ai_event_options, + _user_distinct_id, _capture_processor_event, + _resolve_ai_client, finalize_ai_content, _format_error_summary, _privacy_mode_enabled, @@ -101,6 +103,7 @@ def __init__( privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None, + options: Optional[Dict[str, Any]] = None, ): """ Initialize the PostHog tracing processor. @@ -112,12 +115,17 @@ def __init__( privacy_mode: If True, redacts input/output content from events. groups: Optional PostHog groups to associate with all events. properties: Optional additional properties to include with all events. + options: Optional capture options for all events, such as + ``{"cookieless_mode": True}``. They win over context options and + ``super_options``. An event without a distinct ID always sends + ``process_person_profile: False``. """ - self._client = client or setup() + self._client = _resolve_ai_client(client) self._distinct_id = distinct_id self._privacy_mode = privacy_mode self._groups = groups or {} self._properties = properties or {} + self._options = _ai_event_options(options) # Track span start times for latency calculation self._span_start_times: Dict[str, float] = {} @@ -193,14 +201,20 @@ def _capture_event( properties: Dict[str, Any], distinct_id: Optional[str] = None, ) -> None: - """Capture an event without allowing telemetry failures to escape.""" + """Capture an event without allowing telemetry failures to escape. + + Without a distinct ID, the event is personless and uses its trace ID. + """ _capture_processor_event( self._client, event, properties, default_properties=self._properties, - distinct_id=distinct_id, + distinct_id=_user_distinct_id(distinct_id) + or properties.get("$ai_trace_id"), groups=self._groups, + personless=_user_distinct_id(distinct_id) is None, + default_options=self._options, ) def on_trace_start(self, trace: Trace) -> None: @@ -248,42 +262,30 @@ def on_trace_end(self, trace: Trace) -> None: "$ai_framework": "openai-agents", } - self._add_trace_details(properties, latency, group_id, metadata) + if latency is not None: + properties["$ai_latency"] = latency - if distinct_id is None: - properties["$process_person_profile"] = False + # The Agents SDK group_id links traces from one conversation, which is + # exactly what PostHog calls a session. $ai_group_id is still emitted + # for anyone already querying it. + if group_id: + properties["$ai_session_id"] = group_id + properties["$ai_group_id"] = group_id + + # Include trace metadata if present + if metadata: + properties["$ai_trace_metadata"] = self._with_privacy_mode( + _ensure_serializable(metadata) + ) self._capture_event( event="$ai_trace", - distinct_id=distinct_id or trace_id, + distinct_id=distinct_id, properties=properties, ) except Exception as e: log.debug(f"Error in on_trace_end: {e}") - def _add_trace_details( - self, - properties: Dict[str, Any], - latency: Optional[float], - group_id: Any, - metadata: Any, - ) -> None: - if latency is not None: - properties["$ai_latency"] = latency - - # The Agents SDK group_id links traces from one conversation, which is - # exactly what PostHog calls a session. $ai_group_id is still emitted - # for anyone already querying it. - if group_id: - properties["$ai_session_id"] = group_id - properties["$ai_group_id"] = group_id - - # Include trace metadata if present - if metadata: - properties["$ai_trace_metadata"] = self._with_privacy_mode( - _ensure_serializable(metadata) - ) - def on_span_start(self, span: Span[Any]) -> None: """Called when a new span begins.""" try: @@ -301,95 +303,189 @@ def on_span_end(self, span: Span[Any]) -> None: parent_id = span.parent_id span_data = span.span_data - latency = self._span_latency(span, span_id) + # Calculate latency + start_time = self._span_start_times.pop(span_id, None) + if start_time: + latency = time.time() - start_time + else: + # Fall back to parsing timestamps + started = _parse_iso_timestamp(span.started_at) + ended = _parse_iso_timestamp(span.ended_at) + latency = (ended - started) if (started and ended) else 0 # Get user-provided distinct ID from trace metadata (resolved at trace start). - # None means no user-provided ID — use trace_id as fallback in personless mode, - # matching the langchain/openai pattern: `distinct_id or trace_id`. + # None means no user-provided ID: _capture_event falls back to the + # trace ID and makes the event personless. trace_info = self._trace_metadata.get(trace_id, {}) distinct_id = trace_info.get("distinct_id") or self._get_distinct_id(None) # Get group_id from trace metadata for linking group_id = self._get_group_id(trace_id) - error_properties = self._span_error_properties(span.error) - - # Personless mode: no user-provided distinct_id, fallback to trace_id - if distinct_id is None: - error_properties["$process_person_profile"] = False - distinct_id = trace_id - - handler = self._span_handler(span_data) - handler( - span_data, - trace_id, - span_id, - parent_id, - latency, - distinct_id, - group_id, - error_properties, - ) + # Get error info if present + error_info = span.error + error_properties = {} + if error_info: + if isinstance(error_info, dict): + error_message = error_info.get("message", str(error_info)) + error_type_raw = error_info.get("type", "") + else: + error_message = str(error_info) + error_type_raw = "" + + # Categorize error type for cross-provider filtering/alerting + error_type = "unknown" + if ( + "ModelBehaviorError" in error_type_raw + or "ModelBehaviorError" in error_message + ): + error_type = "model_behavior_error" + elif "UserError" in error_type_raw or "UserError" in error_message: + error_type = "user_error" + elif ( + "InputGuardrailTripwireTriggered" in error_type_raw + or "InputGuardrailTripwireTriggered" in error_message + ): + error_type = "input_guardrail_triggered" + elif ( + "OutputGuardrailTripwireTriggered" in error_type_raw + or "OutputGuardrailTripwireTriggered" in error_message + ): + error_type = "output_guardrail_triggered" + elif ( + "MaxTurnsExceeded" in error_type_raw + or "MaxTurnsExceeded" in error_message + ): + error_type = "max_turns_exceeded" + + error_properties = { + "$ai_is_error": True, + "$ai_error": ( + self._summarize_span_error(error_info) + if self._privacy_enabled() + else error_message + ), + "$ai_error_type": error_type, + } + + # Dispatch based on span data type + if isinstance(span_data, GenerationSpanData): + self._handle_generation_span( + span_data, + trace_id, + span_id, + parent_id, + latency, + distinct_id, + group_id, + error_properties, + ) + elif isinstance(span_data, FunctionSpanData): + self._handle_function_span( + span_data, + trace_id, + span_id, + parent_id, + latency, + distinct_id, + group_id, + error_properties, + ) + elif isinstance(span_data, AgentSpanData): + self._handle_agent_span( + span_data, + trace_id, + span_id, + parent_id, + latency, + distinct_id, + group_id, + error_properties, + ) + elif isinstance(span_data, HandoffSpanData): + self._handle_handoff_span( + span_data, + trace_id, + span_id, + parent_id, + latency, + distinct_id, + group_id, + error_properties, + ) + elif isinstance(span_data, GuardrailSpanData): + self._handle_guardrail_span( + span_data, + trace_id, + span_id, + parent_id, + latency, + distinct_id, + group_id, + error_properties, + ) + elif isinstance(span_data, ResponseSpanData): + self._handle_response_span( + span_data, + trace_id, + span_id, + parent_id, + latency, + distinct_id, + group_id, + error_properties, + ) + elif isinstance(span_data, CustomSpanData): + self._handle_custom_span( + span_data, + trace_id, + span_id, + parent_id, + latency, + distinct_id, + group_id, + error_properties, + ) + elif isinstance( + span_data, (TranscriptionSpanData, SpeechSpanData, SpeechGroupSpanData) + ): + self._handle_audio_span( + span_data, + trace_id, + span_id, + parent_id, + latency, + distinct_id, + group_id, + error_properties, + ) + elif isinstance(span_data, MCPListToolsSpanData): + self._handle_mcp_span( + span_data, + trace_id, + span_id, + parent_id, + latency, + distinct_id, + group_id, + error_properties, + ) + else: + # Unknown span type - capture as generic span + self._handle_generic_span( + span_data, + trace_id, + span_id, + parent_id, + latency, + distinct_id, + group_id, + error_properties, + ) except Exception as e: log.debug(f"Error in on_span_end: {e}") - def _span_latency(self, span: Span[Any], span_id: str) -> float: - # Calculate latency - start_time = self._span_start_times.pop(span_id, None) - if start_time: - return time.time() - start_time - else: - # Fall back to parsing timestamps - started = _parse_iso_timestamp(span.started_at) - ended = _parse_iso_timestamp(span.ended_at) - return (ended - started) if (started and ended) else 0 - - def _span_error_properties(self, error_info: Any) -> Dict[str, Any]: - # Get error info if present - error_properties = {} - if error_info: - if isinstance(error_info, dict): - error_message = error_info.get("message", str(error_info)) - error_type_raw = error_info.get("type", "") - else: - error_message = str(error_info) - error_type_raw = "" - - error_type = _categorize_span_error(error_type_raw, error_message) - - error_properties = { - "$ai_is_error": True, - "$ai_error": ( - self._summarize_span_error(error_info) - if self._privacy_enabled() - else error_message - ), - "$ai_error_type": error_type, - } - - return error_properties - - def _span_handler(self, span_data: Any) -> Callable[..., None]: - for span_types, handler_name in ( - (GenerationSpanData, "_handle_generation_span"), - (FunctionSpanData, "_handle_function_span"), - (AgentSpanData, "_handle_agent_span"), - (HandoffSpanData, "_handle_handoff_span"), - (GuardrailSpanData, "_handle_guardrail_span"), - (ResponseSpanData, "_handle_response_span"), - (CustomSpanData, "_handle_custom_span"), - ( - (TranscriptionSpanData, SpeechSpanData, SpeechGroupSpanData), - "_handle_audio_span", - ), - (MCPListToolsSpanData, "_handle_mcp_span"), - ): - if isinstance(span_data, span_types): - return getattr(self, handler_name) - # Unknown span type - capture as generic span. - return self._handle_generic_span - def _base_properties( self, trace_id: str, @@ -421,7 +517,7 @@ def _handle_generation_span( span_id: str, parent_id: Optional[str], latency: float, - distinct_id: str, + distinct_id: Optional[str], group_id: Optional[str], error_properties: Dict[str, Any], ) -> None: @@ -464,19 +560,20 @@ def _handle_generation_span( _ensure_serializable(span_data.output), self._client ) ), - **_token_properties(input_tokens, output_tokens), + **({"$ai_input_tokens": input_tokens} if input_tokens is not None else {}), + **( + {"$ai_output_tokens": output_tokens} + if output_tokens is not None + else {} + ), + # Sum of the reported sides; omitted when neither side was reported. + **( + {"$ai_total_tokens": (input_tokens or 0) + (output_tokens or 0)} + if input_tokens is not None or output_tokens is not None + else {} + ), } - self._add_generation_usage_details(properties, usage, span_data) - - self._capture_event("$ai_generation", properties, distinct_id) - - def _add_generation_usage_details( - self, - properties: Dict[str, Any], - usage: Dict[str, Any], - span_data: GenerationSpanData, - ) -> None: # Add optional token fields if present. The Agents SDK nests cached # tokens under the usage details fields; flat keys are kept for custom # models. Nested reasoning is not forwarded: compatible providers count @@ -510,6 +607,8 @@ def _add_generation_usage_details( if finish_reason is not None: properties["$ai_stop_reason"] = finish_reason + self._capture_event("$ai_generation", properties, distinct_id) + def _handle_function_span( self, span_data: FunctionSpanData, @@ -517,7 +616,7 @@ def _handle_function_span( span_id: str, parent_id: Optional[str], latency: float, - distinct_id: str, + distinct_id: Optional[str], group_id: Optional[str], error_properties: Dict[str, Any], ) -> None: @@ -550,7 +649,7 @@ def _handle_agent_span( span_id: str, parent_id: Optional[str], latency: float, - distinct_id: str, + distinct_id: Optional[str], group_id: Optional[str], error_properties: Dict[str, Any], ) -> None: @@ -579,7 +678,7 @@ def _handle_handoff_span( span_id: str, parent_id: Optional[str], latency: float, - distinct_id: str, + distinct_id: Optional[str], group_id: Optional[str], error_properties: Dict[str, Any], ) -> None: @@ -603,7 +702,7 @@ def _handle_guardrail_span( span_id: str, parent_id: Optional[str], latency: float, - distinct_id: str, + distinct_id: Optional[str], group_id: Optional[str], error_properties: Dict[str, Any], ) -> None: @@ -626,7 +725,7 @@ def _handle_response_span( span_id: str, parent_id: Optional[str], latency: float, - distinct_id: str, + distinct_id: Optional[str], group_id: Optional[str], error_properties: Dict[str, Any], ) -> None: @@ -634,9 +733,14 @@ def _handle_response_span( response = span_data.response response_id = response.id if response else None - usage, total_cost_usd, input_tokens, output_tokens = _response_usage_counts( - response - ) + # Try to extract usage from response + usage = getattr(response, "usage", None) if response else None + total_cost_usd = getattr(usage, "cost", None) if usage else None + # None when the response never reported a count: absent means unknown, + # 0 is a report of nothing. + input_tokens = getattr(usage, "input_tokens", None) if usage else None + output_tokens = getattr(usage, "output_tokens", None) if usage else None + # Try to extract model from response model = getattr(response, "model", None) if response else None @@ -649,7 +753,18 @@ def _handle_response_span( "$ai_input": self._with_privacy_mode( finalize_ai_content(_ensure_serializable(span_data.input), self._client) ), - **_token_properties(input_tokens, output_tokens), + **({"$ai_input_tokens": input_tokens} if input_tokens is not None else {}), + **( + {"$ai_output_tokens": output_tokens} + if output_tokens is not None + else {} + ), + # Sum of the reported sides; omitted when neither side was reported. + **( + {"$ai_total_tokens": (input_tokens or 0) + (output_tokens or 0)} + if input_tokens is not None or output_tokens is not None + else {} + ), } if total_cost_usd is not None: @@ -688,7 +803,7 @@ def _handle_custom_span( span_id: str, parent_id: Optional[str], latency: float, - distinct_id: str, + distinct_id: Optional[str], group_id: Optional[str], error_properties: Dict[str, Any], ) -> None: @@ -713,7 +828,7 @@ def _handle_audio_span( span_id: str, parent_id: Optional[str], latency: float, - distinct_id: str, + distinct_id: Optional[str], group_id: Optional[str], error_properties: Dict[str, Any], ) -> None: @@ -728,20 +843,6 @@ def _handle_audio_span( "$ai_span_type": span_type, } - self._add_audio_metadata(properties, span_data) - - self._add_audio_input(properties, span_data, span_type) - - if hasattr(span_data, "output") and isinstance(span_data.output, str): - properties["$ai_output_state"] = self._with_privacy_mode( - finalize_ai_content( - _ensure_serializable(span_data.output), self._client - ) - ) - - self._capture_event("$ai_span", properties, distinct_id) - - def _add_audio_metadata(self, properties: Dict[str, Any], span_data: Any) -> None: # Add model info if available if hasattr(span_data, "model") and span_data.model: properties["$ai_model"] = span_data.model @@ -762,9 +863,6 @@ def _add_audio_metadata(self, properties: Dict[str, Any], span_data: Any) -> Non if hasattr(span_data, "output_format"): properties["audio_output_format"] = span_data.output_format - def _add_audio_input( - self, properties: Dict[str, Any], span_data: Any, span_type: str - ) -> None: # Capture the input. For speech (TTS) spans the input is the text to # synthesize. For transcription spans the input is the base64-encoded # audio — a bare string with no key/parent context the structural @@ -791,6 +889,15 @@ def _add_audio_input( ) ) + if hasattr(span_data, "output") and isinstance(span_data.output, str): + properties["$ai_output_state"] = self._with_privacy_mode( + finalize_ai_content( + _ensure_serializable(span_data.output), self._client + ) + ) + + self._capture_event("$ai_span", properties, distinct_id) + def _redact_audio_model_config(self, model_config: Any) -> Any: # The STT prompt and TTS instructions are user-authored text. if not isinstance(model_config, dict) or not self._privacy_enabled(): @@ -807,7 +914,7 @@ def _handle_mcp_span( span_id: str, parent_id: Optional[str], latency: float, - distinct_id: str, + distinct_id: Optional[str], group_id: Optional[str], error_properties: Dict[str, Any], ) -> None: @@ -831,7 +938,7 @@ def _handle_generic_span( span_id: str, parent_id: Optional[str], latency: float, - distinct_id: str, + distinct_id: Optional[str], group_id: Optional[str], error_properties: Dict[str, Any], ) -> None: @@ -875,43 +982,3 @@ def force_flush(self) -> None: self._client.flush() except Exception as e: log.debug(f"Error in force_flush: {e}") - - -def _categorize_span_error(error_type_raw: str, error_message: str) -> str: - # Ordered categories preserve precedence when a message names several errors. - for name, category in ( - ("ModelBehaviorError", "model_behavior_error"), - ("UserError", "user_error"), - ("InputGuardrailTripwireTriggered", "input_guardrail_triggered"), - ("OutputGuardrailTripwireTriggered", "output_guardrail_triggered"), - ("MaxTurnsExceeded", "max_turns_exceeded"), - ): - if name in error_type_raw or name in error_message: - return category - return "unknown" - - -def _token_properties(input_tokens: Any, output_tokens: Any) -> Dict[str, Any]: - properties = {} - if input_tokens is not None: - properties["$ai_input_tokens"] = input_tokens - if output_tokens is not None: - properties["$ai_output_tokens"] = output_tokens - # Sum of the reported sides; omitted when neither side was reported. - if input_tokens is not None or output_tokens is not None: - properties["$ai_total_tokens"] = (input_tokens or 0) + (output_tokens or 0) - return properties - - -def _response_usage_counts( - response: Any, -) -> tuple[Any, Optional[float], Optional[int], Optional[int]]: - # Try to extract usage from response - usage = getattr(response, "usage", None) if response else None - total_cost_usd = getattr(usage, "cost", None) if usage else None - # None when the response never reported a count: absent means unknown, - # 0 is a report of nothing. - input_tokens = getattr(usage, "input_tokens", None) if usage else None - output_tokens = getattr(usage, "output_tokens", None) if usage else None - - return usage, total_cost_usd, input_tokens, output_tokens diff --git a/posthog/ai/prompts.py b/posthog/ai/prompts.py index 6b40c4a62..4da454703 100644 --- a/posthog/ai/prompts.py +++ b/posthog/ai/prompts.py @@ -17,9 +17,7 @@ from dataclasses import dataclass from typing import Any, Dict, List, Literal, Optional, Union, overload -from requests import Response as _Response - -from posthog.capture_v1 import _parse_retry_after +from posthog.capture_send import _parse_retry_after from posthog.request import USER_AGENT, _get_session from posthog.utils import remove_trailing_slash @@ -464,42 +462,6 @@ def get_all(self, *, label: Optional[str] = None) -> Dict[str, PromptResult]: self._maybe_capture_error(error, name="*", version=None, label=label) raise - resolved_rows, skipped = self._resolve_prompt_rows(rows, label) - - now = time.time() - results: Dict[str, PromptResult] = {} - for row in resolved_rows: - config = _extract_config(row) - self._cache[_cache_key(row["name"], None, label)] = CachedPrompt( - prompt=row["prompt"], - fetched_at=now, - name=row["name"], - version=row["version"], - label=label, - config=config, - ) - results[row["name"]] = PromptResult( - source="api", - prompt=row["prompt"], - name=row["name"], - version=row["version"], - label=label, - config=copy.deepcopy(config), - ) - - if skipped: - log.warning( - "[PostHog Prompts] Skipped %d prompt(s) that did not resolve label %r: %s", - len(skipped), - label, - ", ".join(skipped), - ) - - return results - - def _resolve_prompt_rows( - self, rows: List[Dict[str, Any]], label: Optional[str] - ) -> tuple[List[Dict[str, Any]], List[str]]: reference = _prompt_list_reference(label) # Validate every row before caching any, so a rejected batch leaves @@ -552,7 +514,36 @@ def _resolve_prompt_rows( self._maybe_capture_error(compat_error, name="*", version=None, label=label) raise compat_error - return resolved_rows, skipped + now = time.time() + results: Dict[str, PromptResult] = {} + for row in resolved_rows: + config = _extract_config(row) + self._cache[_cache_key(row["name"], None, label)] = CachedPrompt( + prompt=row["prompt"], + fetched_at=now, + name=row["name"], + version=row["version"], + label=label, + config=config, + ) + results[row["name"]] = PromptResult( + source="api", + prompt=row["prompt"], + name=row["name"], + version=row["version"], + label=label, + config=copy.deepcopy(config), + ) + + if skipped: + log.warning( + "[PostHog Prompts] Skipped %d prompt(s) that did not resolve label %r: %s", + len(skipped), + label, + ", ".join(skipped), + ) + + return results def _get_internal( self, @@ -578,9 +569,38 @@ def _get_internal( cached = self._cache.get(cache_key) now = time.time() - cached_result = _cached_prompt_result(cached, now, ttl) - if cached_result is not None: - return cached_result + if cached is not None: + is_fresh = (now - cached.fetched_at) < ttl + + if is_fresh: + return PromptResult( + source="cache", + prompt=cached.prompt, + name=cached.name, + version=cached.version, + label=cached.label, + # Copied so a caller mutating result.config can't pollute the + # cache entry that later cache hits are served from. + config=copy.deepcopy(cached.config), + ) + + # A failed refetch left this entry in cooldown. Serving it keeps one + # throttled client from turning every later get() into another + # request, which is what holds it against the limit. A zero TTL is + # an explicit request to refetch on every read, so it opts out. + if ( + ttl > 0 + and cached.retry_not_before is not None + and now < cached.retry_not_before + ): + return PromptResult( + source="stale_cache", + prompt=cached.prompt, + name=cached.name, + version=cached.version, + label=cached.label, + config=copy.deepcopy(cached.config), + ) # Try to fetch from API try: @@ -649,7 +669,11 @@ def _fetch_prompt_once( self._in_flight[cache_key] = pending if not is_leader: - return _wait_for_prompt(pending) + pending.done.wait() + if pending.error is not None: + raise pending.error + assert pending.result is not None + return pending.result try: data = self._fetch_prompt_from_api(name, version, label) @@ -827,7 +851,17 @@ def _fetch_prompt_list_from_api(self, label: Optional[str]) -> List[Dict[str, An response = _get_session().get(url, headers=headers, timeout=10) - _raise_prompt_response_error(response, reference) + if not response.ok: + if response.status_code == 401: + raise _authentication_error(reference) + if response.status_code == 403: + raise _access_denied_error(reference) + raise PromptFetchError( + f"[PostHog Prompts] Failed to fetch {reference}: HTTP {response.status_code}", + _parse_retry_after_seconds(response.headers.get("Retry-After")) + if response.status_code == 429 + else None, + ) try: data = response.json() @@ -843,7 +877,18 @@ def _fetch_prompt_list_from_api(self, label: Optional[str]) -> List[Dict[str, An rows.extend(data["results"]) - url = _prompt_next_url(data, self._host, reference) + # The Authorization header goes to every followed link, so a link + # off the configured host must never be requested. + next_url = data.get("next") + if next_url is not None and ( + not isinstance(next_url, str) + or not _is_same_origin(next_url, self._host) + ): + raise Exception( + f"[PostHog Prompts] Refusing to follow a pagination link off the " + f"configured host while fetching {reference}." + ) + url = next_url pages += 1 return rows @@ -909,91 +954,16 @@ def _fetch_prompt_from_api( else None, ) - return _prompt_response_data(response, prompt_title) - - -def _cached_prompt_result( - cached: Optional[CachedPrompt], now: float, ttl: float -) -> Optional[PromptResult]: - if cached is not None: - is_fresh = (now - cached.fetched_at) < ttl - - if is_fresh: - return PromptResult( - source="cache", - prompt=cached.prompt, - name=cached.name, - version=cached.version, - label=cached.label, - # Copied so a caller mutating result.config can't pollute the - # cache entry that later cache hits are served from. - config=copy.deepcopy(cached.config), + try: + data = response.json() + except Exception: + raise Exception( + f"[PostHog Prompts] Invalid response format for {prompt_title}" ) - # A failed refetch left this entry in cooldown. Serving it keeps one - # throttled client from turning every later get() into another - # request, which is what holds it against the limit. A zero TTL is - # an explicit request to refetch on every read, so it opts out. - if ( - ttl > 0 - and cached.retry_not_before is not None - and now < cached.retry_not_before - ): - return PromptResult( - source="stale_cache", - prompt=cached.prompt, - name=cached.name, - version=cached.version, - label=cached.label, - config=copy.deepcopy(cached.config), + if not _is_prompt_api_response(data): + raise Exception( + f"[PostHog Prompts] Invalid response format for {prompt_title}" ) - return None - - -def _wait_for_prompt(pending: _InFlightFetch) -> CachedPrompt: - pending.done.wait() - if pending.error is not None: - raise pending.error - assert pending.result is not None - return pending.result - - -def _raise_prompt_response_error(response: _Response, reference: str) -> None: - if not response.ok: - if response.status_code == 401: - raise _authentication_error(reference) - if response.status_code == 403: - raise _access_denied_error(reference) - raise PromptFetchError( - f"[PostHog Prompts] Failed to fetch {reference}: HTTP {response.status_code}", - _parse_retry_after_seconds(response.headers.get("Retry-After")) - if response.status_code == 429 - else None, - ) - - -def _prompt_response_data(response: _Response, prompt_title: str) -> Dict[str, Any]: - try: - data = response.json() - except Exception: - raise Exception(f"[PostHog Prompts] Invalid response format for {prompt_title}") - - if not _is_prompt_api_response(data): - raise Exception(f"[PostHog Prompts] Invalid response format for {prompt_title}") - - return data - - -def _prompt_next_url(data: Dict[str, Any], host: str, reference: str) -> Optional[str]: - # The Authorization header goes to every followed link, so a link - # off the configured host must never be requested. - next_url = data.get("next") - if next_url is not None and ( - not isinstance(next_url, str) or not _is_same_origin(next_url, host) - ): - raise Exception( - f"[PostHog Prompts] Refusing to follow a pagination link off the " - f"configured host while fetching {reference}." - ) - return next_url + return data diff --git a/posthog/ai/types.py b/posthog/ai/types.py index 1fc5555fa..630141ef3 100644 --- a/posthog/ai/types.py +++ b/posthog/ai/types.py @@ -144,3 +144,4 @@ class StreamingEventData(TypedDict): stop_reason: Optional[str] service_tier: NotRequired[Optional[str]] error: NotRequired[Optional[BaseException]] # raised mid-stream, if any + options: NotRequired[Optional[Dict[str, Any]]] # the caller's posthog_options diff --git a/posthog/ai/utils.py b/posthog/ai/utils.py index 17dc0500d..62bd937a6 100644 --- a/posthog/ai/utils.py +++ b/posthog/ai/utils.py @@ -6,12 +6,12 @@ import uuid from typing import Any, Callable, Dict, List, Optional, Tuple, cast -from posthog import get_tags, identify_context, new_context, tag, contexts +from posthog import get_tags, identify_context, new_context, setup, tag, contexts from posthog.ai.gateway import warn_if_posthog_ai_gateway -from posthog.ai.sanitization import _full_ai_capture_enabled, redact_media +from posthog.ai.sanitization import redact_media from posthog.ai.sanitization import sanitize_messages # noqa: F401 -- re-exported for back-compat from posthog.ai.types import FormattedMessage, StreamingEventData, TokenUsage -from posthog.client import Client as PostHogClient +from posthog.client import Client as PostHogClient, _explicit_distinct_id from ..version import VERSION as _POSTHOG_VERSION @@ -35,10 +35,6 @@ ) -def _is_token_count(value: Any) -> bool: - return isinstance(value, int) and not isinstance(value, bool) and value >= 0 - - def _extract_cache_creation_ttl_breakdown( token_details: Any, ) -> Optional[Tuple[int, int]]: @@ -50,7 +46,11 @@ def _extract_cache_creation_ttl_breakdown( token_details.get("ephemeral_5m_input_tokens"), token_details.get("ephemeral_1h_input_tokens"), ) - if not all(_is_token_count(value) for value in values if value is not None): + if not any(value is not None for value in values) or not all( + isinstance(value, int) and not isinstance(value, bool) and value >= 0 + for value in values + if value is not None + ): return None breakdown = (values[0] or 0, values[1] or 0) @@ -67,22 +67,74 @@ def _get_tokens_source( return "sdk" -def _ai_lane_enabled(ph_client) -> bool: - """The client's full-AI-capture opt-in routes wrapper events onto the AI lane.""" - return _full_ai_capture_enabled(ph_client) +def _user_distinct_id(distinct_id: Any) -> Any: + """The caller's distinct id as given, or None when it is missing, empty or whitespace.""" + return distinct_id if _explicit_distinct_id(distinct_id) is not None else None -def _capture_ai_event(ph_client, event: str, **kwargs): - """Capture a wrapper-emitted AI event with the PostHog AI library identity.""" +def _ai_event_options(value: Any) -> Dict[str, Any]: + """Return a copy of a caller's ``posthog_options``, or ``{}`` when it is not a dict.""" + if value is None: + return {} + if not isinstance(value, dict): + logging.getLogger("posthog").warning( + "posthog_options must be a dict, got %s. Sending the event without them.", + type(value).__name__, + ) + return {} + return dict(value) + + +def _capture_ai_event(ph_client, event: str, *, personless: bool = False, **kwargs): + """Capture a wrapper-emitted AI event with the PostHog AI library identity. + + ``options`` are the caller's per-event options. ``personless`` marks an + event whose distinct ID is a fallback, such as a trace ID, not a real user. + """ kwargs["properties"] = { **_AI_LIB_PROPERTIES, **(kwargs.get("properties") or {}), } - if _ai_lane_enabled(ph_client): - capture_ai = getattr(ph_client, "capture_ai", None) - if callable(capture_ai): - return capture_ai(event=event, **kwargs) - return ph_client.capture(event=event, **kwargs) + options = _ai_event_options(kwargs.pop("options", None)) + if personless: + # Set last, so it beats the caller's options as well as legacy + # properties and global or context options: a person profile for a + # fallback ID is always wrong. before_send can still change it. + options["process_person_profile"] = False + if options: + kwargs["options"] = options + return ph_client.capture_ai(event=event, **kwargs) + + +class _AICaptureDisabled: + """Stands in for a client without ``capture_ai``: AI events are dropped, and + every other attribute comes from the client.""" + + def __init__(self, client: Any) -> None: + self._client = client + + def capture_ai(self, *args: Any, **kwargs: Any) -> None: + return None + + def __getattr__(self, name: str) -> Any: + return getattr(self._client, name) + + +def _resolve_ai_client(posthog_client: Optional[PostHogClient]) -> PostHogClient: + """Return the client an AI integration sends through, or the global client. + + The check runs when the integration is built, so the error log appears at + setup. A client object without ``capture_ai`` turns AI capture off for the + integration, and provider calls still work. + """ + client = posthog_client or setup() + if not callable(getattr(client, "capture_ai", None)): + logging.getLogger("posthog").error( + "The PostHog client for an AI integration must implement capture_ai(). " + "AI events from this integration are not captured." + ) + return cast(PostHogClient, _AICaptureDisabled(client)) + return client def _capture_processor_event( @@ -93,11 +145,17 @@ def _capture_processor_event( default_properties: Optional[Dict[str, Any]] = None, distinct_id: Optional[str] = None, groups: Optional[Dict[str, Any]] = None, + personless: bool = False, + options: Optional[Dict[str, Any]] = None, + default_options: Optional[Dict[str, Any]] = None, ) -> None: - """Apply the shared capture policy used by AI SDK processors.""" + """Apply the shared capture policy used by AI SDK processors. + + ``default_options`` win over ``options`` key by key, like + ``default_properties`` over ``properties``. + """ try: - capture = getattr(ph_client, "capture", None) - if not callable(capture): + if not callable(getattr(ph_client, "capture_ai", None)): return _capture_ai_event( @@ -106,6 +164,11 @@ def _capture_processor_event( distinct_id=distinct_id or "unknown", properties={**properties, **(default_properties or {})}, groups=groups, + personless=personless, + options={ + **_ai_event_options(options), + **_ai_event_options(default_options), + }, ) except Exception as exc: logging.getLogger("posthog").debug("Failed to capture PostHog event: %s", exc) @@ -131,15 +194,19 @@ def serialize_raw_usage(raw_usage: Any) -> Optional[Dict[str, Any]]: if isinstance(raw_usage, dict): return raw_usage - # Try Pydantic model_dump() first, then protobuf-style to_dict(). - for method_name in ("model_dump", "to_dict"): - if hasattr(raw_usage, method_name) and callable( - getattr(raw_usage, method_name) - ): - try: - return getattr(raw_usage, method_name)() - except Exception: - pass + # Try Pydantic model_dump() (OpenAI/Anthropic) + if hasattr(raw_usage, "model_dump") and callable(raw_usage.model_dump): + try: + return raw_usage.model_dump() + except Exception: + pass + + # Try to_dict() (some protobuf objects) + if hasattr(raw_usage, "to_dict") and callable(raw_usage.to_dict): + try: + return raw_usage.to_dict() + except Exception: + pass # Try __dict__ / vars() for simple objects try: @@ -147,10 +214,6 @@ def serialize_raw_usage(raw_usage: Any) -> Optional[Dict[str, Any]]: except Exception: pass - return _raw_usage_string(raw_usage) - - -def _raw_usage_string(raw_usage: Any) -> Optional[Dict[str, Any]]: # Last resort: convert to string representation # This ensures we always return something rather than failing try: @@ -174,55 +237,81 @@ def merge_usage_stats( source: TokenUsage that may contain None values mode: Either "incremental" or "cumulative" """ - fields = ( - "input_tokens", - "output_tokens", - "cache_read_input_tokens", - "cache_creation_input_tokens", - "reasoning_tokens", - ) - target_fields = cast(Dict[str, Any], target) - source_fields = cast(Dict[str, Any], source) if mode == "incremental": - for field in fields: - value = source_fields.get(field) - if value is not None: - target_fields[field] = (target_fields.get(field) or 0) + value - _merge_incremental_usage_metadata(target, source) + # Add new values to existing totals + source_input = source.get("input_tokens") + if source_input is not None: + current = target.get("input_tokens") or 0 + target["input_tokens"] = current + source_input + + source_output = source.get("output_tokens") + if source_output is not None: + current = target.get("output_tokens") or 0 + target["output_tokens"] = current + source_output + + source_cache_read = source.get("cache_read_input_tokens") + if source_cache_read is not None: + current = target.get("cache_read_input_tokens") or 0 + target["cache_read_input_tokens"] = current + source_cache_read + + source_cache_creation = source.get("cache_creation_input_tokens") + if source_cache_creation is not None: + current = target.get("cache_creation_input_tokens") or 0 + target["cache_creation_input_tokens"] = current + source_cache_creation + + source_reasoning = source.get("reasoning_tokens") + if source_reasoning is not None: + current = target.get("reasoning_tokens") or 0 + target["reasoning_tokens"] = current + source_reasoning + + source_web_search = source.get("web_search_count") + if source_web_search is not None: + current = target.get("web_search_count") or 0 + target["web_search_count"] = max(current, source_web_search) + + # Carried across, never accumulated: this describes the provider's accounting + # model, so it is the same on every chunk. + source_exclusive = source.get("cache_reporting_exclusive") + if source_exclusive is not None: + target["cache_reporting_exclusive"] = source_exclusive + + # Merge raw_usage to avoid losing data from earlier events + # For Anthropic streaming: message_start has input tokens, message_delta has output + # Note: raw_usage is already serialized by converters, so it's a dict + source_raw_usage = source.get("raw_usage") + if source_raw_usage is not None and isinstance(source_raw_usage, dict): + current_raw_value = target.get("raw_usage") + current_raw: Dict[str, Any] = ( + current_raw_value if isinstance(current_raw_value, dict) else {} + ) + target["raw_usage"] = {**current_raw, **source_raw_usage} + elif mode == "cumulative": - for field in ( - *fields, - "web_search_count", - "cache_reporting_exclusive", - "raw_usage", - ): - if source_fields.get(field) is not None: - target_fields[field] = source_fields[field] + # Replace with latest values (already cumulative) + if source.get("input_tokens") is not None: + target["input_tokens"] = source["input_tokens"] + if source.get("output_tokens") is not None: + target["output_tokens"] = source["output_tokens"] + if source.get("cache_read_input_tokens") is not None: + target["cache_read_input_tokens"] = source["cache_read_input_tokens"] + if source.get("cache_creation_input_tokens") is not None: + target["cache_creation_input_tokens"] = source[ + "cache_creation_input_tokens" + ] + if source.get("reasoning_tokens") is not None: + target["reasoning_tokens"] = source["reasoning_tokens"] + if source.get("web_search_count") is not None: + target["web_search_count"] = source["web_search_count"] + if source.get("cache_reporting_exclusive") is not None: + target["cache_reporting_exclusive"] = source["cache_reporting_exclusive"] + # Note: raw_usage is already serialized by converters, so it's a dict + if source.get("raw_usage") is not None: + target["raw_usage"] = source["raw_usage"] + else: raise ValueError(f"Invalid mode: {mode}. Must be 'incremental' or 'cumulative'") -def _merge_incremental_usage_metadata(target: TokenUsage, source: TokenUsage) -> None: - source_web_search = source.get("web_search_count") - if source_web_search is not None: - target["web_search_count"] = max( - target.get("web_search_count") or 0, source_web_search - ) - # Carried across, never accumulated: this describes the provider's accounting - # model, so it is the same on every chunk. - source_exclusive = source.get("cache_reporting_exclusive") - if source_exclusive is not None: - target["cache_reporting_exclusive"] = source_exclusive - # Anthropic message_start and message_delta report different parts of usage. - # Converters have already serialized raw_usage, so merge dicts without losing - # fields from earlier chunks. - source_raw_usage = source.get("raw_usage") - if source_raw_usage is not None and isinstance(source_raw_usage, dict): - current_raw_value = target.get("raw_usage") - current_raw = current_raw_value if isinstance(current_raw_value, dict) else {} - target["raw_usage"] = {**current_raw, **source_raw_usage} - - def get_model_params( kwargs: Dict[str, Any], served_service_tier: Optional[str] = None ) -> Dict[str, Any]: @@ -384,56 +473,49 @@ def merge_system_prompt( elif provider == "openai": from posthog.ai.openai.openai_converter import format_openai_input - return _merge_openai_system_prompt(kwargs, format_openai_input) + # For OpenAI, handle both Chat Completions and Responses API + messages_param = kwargs.get("messages") + input_param = kwargs.get("input") - # Default case - return empty list - return [] + # Get base formatted messages + messages = format_openai_input(messages_param, input_param) - -def _merge_openai_system_prompt( - kwargs: Dict[str, Any], - format_openai_input: Callable[..., List[FormattedMessage]], -) -> List[FormattedMessage]: - # For OpenAI, handle both Chat Completions and Responses API - messages_param = kwargs.get("messages") - input_param = kwargs.get("input") - - # Get base formatted messages - messages = format_openai_input(messages_param, input_param) - - # Check if system prompt is provided as a separate parameter - if kwargs.get("system") is not None: - has_system = any(msg.get("role") == "system" for msg in messages) - if not has_system: - system_msg = cast( - FormattedMessage, - {"role": "system", "content": kwargs.get("system")}, + # Check if system prompt is provided as a separate parameter + if kwargs.get("system") is not None: + has_system = any(msg.get("role") == "system" for msg in messages) + if not has_system: + system_msg = cast( + FormattedMessage, + {"role": "system", "content": kwargs.get("system")}, + ) + messages = [system_msg] + messages + + # For Responses API, add instructions to the system prompt if provided + if kwargs.get("instructions") is not None: + # Find the system message if it exists + system_idx = next( + (i for i, msg in enumerate(messages) if msg.get("role") == "system"), + None, ) - messages = [system_msg] + messages - - # For Responses API, add instructions to the system prompt if provided - if kwargs.get("instructions") is not None: - # Find the system message if it exists - system_idx = next( - (i for i, msg in enumerate(messages) if msg.get("role") == "system"), - None, - ) - if system_idx is not None: - # Append instructions to existing system message - system_content = messages[system_idx].get("content", "") - messages[system_idx]["content"] = ( - f"{system_content}\n\n{kwargs.get('instructions')}" - ) - else: - # Create a new system message with instructions - instruction_msg = cast( - FormattedMessage, - {"role": "system", "content": kwargs.get("instructions")}, - ) - messages = [instruction_msg] + messages + if system_idx is not None: + # Append instructions to existing system message + system_content = messages[system_idx].get("content", "") + messages[system_idx]["content"] = ( + f"{system_content}\n\n{kwargs.get('instructions')}" + ) + else: + # Create a new system message with instructions + instruction_msg = cast( + FormattedMessage, + {"role": "system", "content": kwargs.get("instructions")}, + ) + messages = [instruction_msg] + messages - return messages + return messages + + # Default case - return empty list + return [] # https://docs.anthropic.com/en/api/errors @@ -494,16 +576,21 @@ def call_llm_and_track_usage( posthog_groups: Optional[Dict[str, Any]], base_url: str, call_method: Callable[..., Any], + *, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ) -> Any: """ Common usage-tracking logic for both sync and async calls. call_method: the llm call method (e.g. openai.chat.completions.create) + posthog_options: capture options for the event. They are not passed to + ``call_method``. """ start_time = time.time() response = None error = None http_status = 200 + usage: TokenUsage = TokenUsage() error_params: Dict[str, Any] = {} with new_context(client=ph_client, capture_exceptions=False): @@ -523,22 +610,128 @@ def call_llm_and_track_usage( # enable_exception_autocapture is True, similar to LangChain callbacks. # See _capture_exception_and_update_properties in langchain/callbacks.py finally: - _capture_llm_call( - start_time, - response, - posthog_trace_id, - posthog_distinct_id, - ph_client, - provider, - kwargs, - posthog_privacy_mode, - http_status, - base_url, - posthog_properties, - error_params, - posthog_groups, + end_time = time.time() + latency = end_time - start_time + + if posthog_trace_id is None: + posthog_trace_id = str(uuid.uuid4()) + + # Check if we have a real user distinct_id (from param or outer context) + has_person_distinct_id = ( + _user_distinct_id(posthog_distinct_id) is not None + or _user_distinct_id(contexts.get_context_distinct_id()) is not None ) + if not has_person_distinct_id: + # Fall back to trace_id as distinct_id when no real user id is available. + identify_context(posthog_trace_id) + + if response and ( + hasattr(response, "usage") + or (provider == "gemini" and hasattr(response, "usage_metadata")) + ): + usage = get_usage(response, provider) + + messages = merge_system_prompt(kwargs, provider) + sanitized_messages = finalize_ai_content(messages, ph_client) + + tag("$ai_provider", provider) + tag("$ai_model", kwargs.get("model") or getattr(response, "model", None)) + served_service_tier = getattr(response, "service_tier", None) + tag("$ai_model_parameters", get_model_params(kwargs, served_service_tier)) + if served_service_tier is not None: + # The explicit served-tier signal cost processing prices from. + tag("$ai_service_tier", served_service_tier) + tag( + "$ai_input", + with_privacy_mode(ph_client, posthog_privacy_mode, sanitized_messages), + ) + tag( + "$ai_output_choices", + with_privacy_mode( + ph_client, + posthog_privacy_mode, + finalize_ai_content(format_response(response, provider), ph_client), + ), + ) + tag("$ai_http_status", http_status) + # Omitted when the provider never reported a count: absent means + # unknown, 0 is a report of nothing. + input_tokens = usage.get("input_tokens") + if input_tokens is not None: + tag("$ai_input_tokens", input_tokens) + output_tokens = usage.get("output_tokens") + if output_tokens is not None: + tag("$ai_output_tokens", output_tokens) + tag("$ai_latency", latency) + tag("$ai_trace_id", posthog_trace_id) + tag("$ai_base_url", str(base_url)) + warn_if_posthog_ai_gateway(base_url) + + available_tool_calls = extract_available_tool_calls(provider, kwargs) + + if available_tool_calls: + tag("$ai_tools", available_tool_calls) + + cache_read = usage.get("cache_read_input_tokens") + if cache_read is not None and cache_read > 0: + tag("$ai_cache_read_input_tokens", cache_read) + + cache_creation = usage.get("cache_creation_input_tokens") + if cache_creation is not None and cache_creation > 0: + tag("$ai_cache_creation_input_tokens", cache_creation) + + cache_reporting_exclusive = usage.get("cache_reporting_exclusive") + if cache_reporting_exclusive is not None: + tag("$ai_cache_reporting_exclusive", cache_reporting_exclusive) + + reasoning = usage.get("reasoning_tokens") + if reasoning is not None and reasoning > 0: + tag("$ai_reasoning_tokens", reasoning) + + web_search_count = usage.get("web_search_count") + if web_search_count is not None and web_search_count > 0: + tag("$ai_web_search_count", web_search_count) + + raw_usage = usage.get("raw_usage") + if raw_usage is not None: + # Already serialized by converters + tag("$ai_usage", raw_usage) + + stop_reason = extract_stop_reason(response, provider) + if stop_reason is not None: + tag("$ai_stop_reason", stop_reason) + + # Process instructions for Responses API + if provider == "openai" and kwargs.get("instructions") is not None: + tag( + "$ai_instructions", + with_privacy_mode( + ph_client, posthog_privacy_mode, kwargs.get("instructions") + ), + ) + + # send the event to posthog + if callable(getattr(ph_client, "capture_ai", None)): + sdk_tags = get_tags() + merged_properties = { + **sdk_tags, + **(posthog_properties or {}), + **(error_params or {}), + } + merged_properties["$ai_tokens_source"] = _get_tokens_source( + sdk_tags, posthog_properties + ) + _capture_ai_event( + ph_client, + "$ai_generation", + distinct_id=contexts.get_context_distinct_id(), + properties=merged_properties, + groups=posthog_groups, + personless=not has_person_distinct_id, + options=posthog_options, + ) + if error: raise error @@ -555,12 +748,15 @@ async def call_llm_and_track_usage_async( posthog_groups: Optional[Dict[str, Any]], base_url: str, call_async_method: Callable[..., Any], + *, + posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any, ) -> Any: start_time = time.time() response = None error = None http_status = 200 + usage: TokenUsage = TokenUsage() error_params: Dict[str, Any] = {} with new_context(client=ph_client, capture_exceptions=False): @@ -587,198 +783,132 @@ async def call_llm_and_track_usage_async( # enable_exception_autocapture is True, similar to LangChain callbacks. # See _capture_exception_and_update_properties in langchain/callbacks.py finally: - _capture_llm_call( - start_time, - response, - posthog_trace_id, - posthog_distinct_id, - ph_client, - provider, - kwargs, - posthog_privacy_mode, - http_status, - base_url, - posthog_properties, - error_params, - posthog_groups, - ) + end_time = time.time() + latency = end_time - start_time - if error: - raise error - - return response - - -def _capture_llm_call( - start_time: float, - response: Any, - posthog_trace_id: Optional[str], - posthog_distinct_id: Optional[str], - ph_client: PostHogClient, - provider: str, - kwargs: Dict[str, Any], - posthog_privacy_mode: bool, - http_status: int, - base_url: str, - posthog_properties: Optional[Dict[str, Any]], - error_params: Dict[str, Any], - posthog_groups: Optional[Dict[str, Any]], -) -> None: - usage: TokenUsage = TokenUsage() - end_time = time.time() - latency = end_time - start_time - - if posthog_trace_id is None: - posthog_trace_id = str(uuid.uuid4()) - - # Check if we have a real user distinct_id (from param or outer context) - has_person_distinct_id = ( - posthog_distinct_id is not None - or contexts.get_context_distinct_id() is not None - ) - - if not has_person_distinct_id: - # Fall back to trace_id as distinct_id when no real user id is available. - identify_context(posthog_trace_id) - - if response and ( - hasattr(response, "usage") - or (provider == "gemini" and hasattr(response, "usage_metadata")) - ): - usage = get_usage(response, provider) - - _tag_llm_content(response, provider, kwargs, ph_client, posthog_privacy_mode) - tag("$ai_http_status", http_status) - _tag_reported_token_counts(usage) - tag("$ai_latency", latency) - tag("$ai_trace_id", posthog_trace_id) - tag("$ai_base_url", str(base_url)) - warn_if_posthog_ai_gateway(base_url) - - available_tool_calls = extract_available_tool_calls(provider, kwargs) - - if available_tool_calls: - tag("$ai_tools", available_tool_calls) - - _tag_optional_usage(usage) - _capture_tagged_llm_event( - response, - provider, - kwargs, - ph_client, - posthog_privacy_mode, - has_person_distinct_id, - posthog_properties, - error_params, - posthog_groups, - ) - - -def _tag_llm_content( - response: Any, - provider: str, - kwargs: Dict[str, Any], - ph_client: PostHogClient, - posthog_privacy_mode: bool, -) -> None: - messages = merge_system_prompt(kwargs, provider) - sanitized_messages = finalize_ai_content(messages, ph_client) - - tag("$ai_provider", provider) - tag("$ai_model", kwargs.get("model") or getattr(response, "model", None)) - served_service_tier = getattr(response, "service_tier", None) - tag("$ai_model_parameters", get_model_params(kwargs, served_service_tier)) - if served_service_tier is not None: - # The explicit served-tier signal cost processing prices from. - tag("$ai_service_tier", served_service_tier) - tag( - "$ai_input", - with_privacy_mode(ph_client, posthog_privacy_mode, sanitized_messages), - ) - tag( - "$ai_output_choices", - with_privacy_mode( - ph_client, - posthog_privacy_mode, - finalize_ai_content(format_response(response, provider), ph_client), - ), - ) - - -def _tag_reported_token_counts(usage: TokenUsage) -> None: - # Omitted when the provider never reported a count: absent means - # unknown, 0 is a report of nothing. - input_tokens = usage.get("input_tokens") - if input_tokens is not None: - tag("$ai_input_tokens", input_tokens) - output_tokens = usage.get("output_tokens") - if output_tokens is not None: - tag("$ai_output_tokens", output_tokens) - - -def _tag_optional_usage(usage: TokenUsage) -> None: - for field in ("cache_read_input_tokens", "cache_creation_input_tokens"): - value = cast(Optional[int], usage.get(field)) - if value is not None and value > 0: - tag(f"$ai_{field}", value) - exclusive = usage.get("cache_reporting_exclusive") - if exclusive is not None: - tag("$ai_cache_reporting_exclusive", exclusive) - for field in ("reasoning_tokens", "web_search_count"): - value = cast(Optional[int], usage.get(field)) - if value is not None and value > 0: - tag(f"$ai_{field}", value) - raw_usage = usage.get("raw_usage") - if raw_usage is not None: - # Already serialized by converters - tag("$ai_usage", raw_usage) + if posthog_trace_id is None: + posthog_trace_id = str(uuid.uuid4()) + # Check if we have a real user distinct_id (from param or outer context) + has_person_distinct_id = ( + _user_distinct_id(posthog_distinct_id) is not None + or _user_distinct_id(contexts.get_context_distinct_id()) is not None + ) -def _capture_tagged_llm_event( - response: Any, - provider: str, - kwargs: Dict[str, Any], - ph_client: PostHogClient, - posthog_privacy_mode: bool, - has_person_distinct_id: bool, - posthog_properties: Optional[Dict[str, Any]], - error_params: Dict[str, Any], - posthog_groups: Optional[Dict[str, Any]], -) -> None: - stop_reason = extract_stop_reason(response, provider) - if stop_reason is not None: - tag("$ai_stop_reason", stop_reason) + if not has_person_distinct_id: + # Fall back to trace_id as distinct_id when no real user id is available. + identify_context(posthog_trace_id) + + if response and ( + hasattr(response, "usage") + or (provider == "gemini" and hasattr(response, "usage_metadata")) + ): + usage = get_usage(response, provider) + + messages = merge_system_prompt(kwargs, provider) + sanitized_messages = finalize_ai_content(messages, ph_client) + + tag("$ai_provider", provider) + tag("$ai_model", kwargs.get("model") or getattr(response, "model", None)) + served_service_tier = getattr(response, "service_tier", None) + tag("$ai_model_parameters", get_model_params(kwargs, served_service_tier)) + if served_service_tier is not None: + # The explicit served-tier signal cost processing prices from. + tag("$ai_service_tier", served_service_tier) + tag( + "$ai_input", + with_privacy_mode(ph_client, posthog_privacy_mode, sanitized_messages), + ) + tag( + "$ai_output_choices", + with_privacy_mode( + ph_client, + posthog_privacy_mode, + finalize_ai_content(format_response(response, provider), ph_client), + ), + ) + tag("$ai_http_status", http_status) + # Omitted when the provider never reported a count: absent means + # unknown, 0 is a report of nothing. + input_tokens = usage.get("input_tokens") + if input_tokens is not None: + tag("$ai_input_tokens", input_tokens) + output_tokens = usage.get("output_tokens") + if output_tokens is not None: + tag("$ai_output_tokens", output_tokens) + tag("$ai_latency", latency) + tag("$ai_trace_id", posthog_trace_id) + tag("$ai_base_url", str(base_url)) + warn_if_posthog_ai_gateway(base_url) + + available_tool_calls = extract_available_tool_calls(provider, kwargs) + + if available_tool_calls: + tag("$ai_tools", available_tool_calls) + + cache_read = usage.get("cache_read_input_tokens") + if cache_read is not None and cache_read > 0: + tag("$ai_cache_read_input_tokens", cache_read) + + cache_creation = usage.get("cache_creation_input_tokens") + if cache_creation is not None and cache_creation > 0: + tag("$ai_cache_creation_input_tokens", cache_creation) + + cache_reporting_exclusive = usage.get("cache_reporting_exclusive") + if cache_reporting_exclusive is not None: + tag("$ai_cache_reporting_exclusive", cache_reporting_exclusive) + + reasoning = usage.get("reasoning_tokens") + if reasoning is not None and reasoning > 0: + tag("$ai_reasoning_tokens", reasoning) + + web_search_count = usage.get("web_search_count") + if web_search_count is not None and web_search_count > 0: + tag("$ai_web_search_count", web_search_count) + + raw_usage = usage.get("raw_usage") + if raw_usage is not None: + # Already serialized by converters + tag("$ai_usage", raw_usage) + + stop_reason = extract_stop_reason(response, provider) + if stop_reason is not None: + tag("$ai_stop_reason", stop_reason) + + # Process instructions for Responses API + if provider == "openai" and kwargs.get("instructions") is not None: + tag( + "$ai_instructions", + with_privacy_mode( + ph_client, posthog_privacy_mode, kwargs.get("instructions") + ), + ) - if not has_person_distinct_id: - tag("$process_person_profile", False) + # send the event to posthog + if callable(getattr(ph_client, "capture_ai", None)): + sdk_tags = get_tags() + merged_properties = { + **sdk_tags, + **(posthog_properties or {}), + **(error_params or {}), + } + merged_properties["$ai_tokens_source"] = _get_tokens_source( + sdk_tags, posthog_properties + ) + _capture_ai_event( + ph_client, + "$ai_generation", + distinct_id=contexts.get_context_distinct_id(), + properties=merged_properties, + groups=posthog_groups, + personless=not has_person_distinct_id, + options=posthog_options, + ) - # Process instructions for Responses API - if provider == "openai" and kwargs.get("instructions") is not None: - tag( - "$ai_instructions", - with_privacy_mode( - ph_client, posthog_privacy_mode, kwargs.get("instructions") - ), - ) + if error: + raise error - # send the event to posthog - if hasattr(ph_client, "capture") and callable(ph_client.capture): - sdk_tags = get_tags() - merged_properties = { - **sdk_tags, - **(posthog_properties or {}), - **(error_params or {}), - } - merged_properties["$ai_tokens_source"] = _get_tokens_source( - sdk_tags, posthog_properties - ) - _capture_ai_event( - ph_client, - "$ai_generation", - distinct_id=contexts.get_context_distinct_id(), - properties=merged_properties, - groups=posthog_groups, - ) + return response def finalize_ai_content(value: Any, ph_client: Any = None) -> Any: @@ -1044,9 +1174,46 @@ def capture_streaming_event( input_tokens = event_data["usage_stats"].get("input_tokens") output_tokens = event_data["usage_stats"].get("output_tokens") - event_properties = _streaming_base_properties( - ph_client, event_data, trace_id, error, input_tokens, output_tokens - ) + # Build base event properties + event_properties = { + "$ai_provider": event_data["provider"], + "$ai_model": event_data["model"], + "$ai_model_parameters": get_model_params( + event_data["kwargs"], event_data.get("service_tier") + ), + **( + {"$ai_service_tier": event_data["service_tier"]} + if event_data.get("service_tier") is not None + else {} + ), + "$ai_input": with_privacy_mode( + ph_client, + event_data["privacy_mode"], + finalize_ai_content(event_data["formatted_input"], ph_client), + ), + "$ai_output_choices": with_privacy_mode( + ph_client, + event_data["privacy_mode"], + finalize_ai_content(event_data["formatted_output"], ph_client), + ), + "$ai_http_status": (_get_http_status(error) if error is not None else 200), + **({"$ai_input_tokens": input_tokens} if input_tokens is not None else {}), + **({"$ai_output_tokens": output_tokens} if output_tokens is not None else {}), + "$ai_latency": event_data["latency"], + "$ai_trace_id": trace_id, + "$ai_base_url": str(event_data["base_url"]), + **(event_data.get("properties") or {}), + **( + { + "$ai_is_error": True, + "$ai_error": _format_ai_error( + ph_client, event_data["privacy_mode"], error + ), + } + if error is not None + else {} + ), + } warn_if_posthog_ai_gateway(event_data["base_url"]) @@ -1067,44 +1234,6 @@ def capture_streaming_event( if available_tools: event_properties["$ai_tools"] = available_tools - _add_streaming_usage(event_properties, event_data, input_tokens, output_tokens) - - # Add stop reason if present - stop_reason = event_data.get("stop_reason") - if stop_reason is not None: - event_properties["$ai_stop_reason"] = stop_reason - - # Handle provider-specific fields - if ( - event_data["provider"] == "openai" - and event_data["kwargs"].get("instructions") is not None - ): - event_properties["$ai_instructions"] = with_privacy_mode( - ph_client, - event_data["privacy_mode"], - event_data["kwargs"]["instructions"], - ) - - if event_data.get("distinct_id") is None: - event_properties["$process_person_profile"] = False - - # Send event to PostHog - if hasattr(ph_client, "capture"): - _capture_ai_event( - ph_client, - "$ai_generation", - distinct_id=event_data.get("distinct_id") or trace_id, - properties=event_properties, - groups=event_data.get("groups"), - ) - - -def _add_streaming_usage( - event_properties: Dict[str, Any], - event_data: StreamingEventData, - input_tokens: Optional[int], - output_tokens: Optional[int], -) -> None: # Add optional token fields. The zero-defaults below only apply when the # provider reported usage at all: a stream interrupted before any report # has nothing to default, and a fabricated 0 would read as a report of @@ -1122,54 +1251,42 @@ def _add_streaming_usage( if isinstance(reasoning, int) and reasoning > 0: event_properties["$ai_reasoning_tokens"] = reasoning else: - _add_optional_streaming_tokens(event_properties, event_data, usage_was_reported) - - _add_streaming_usage_metadata(event_properties, event_data["usage_stats"]) - + optional_token_fields = [ + "cache_read_input_tokens", + "cache_creation_input_tokens", + "reasoning_tokens", + ] -def _add_optional_streaming_tokens( - event_properties: Dict[str, Any], - event_data: StreamingEventData, - usage_was_reported: bool, -) -> None: - optional_token_fields = [ - "cache_read_input_tokens", - "cache_creation_input_tokens", - "reasoning_tokens", - ] - - for field in optional_token_fields: - value = event_data["usage_stats"].get(field) - property_name = f"$ai_{field}" - - # OpenAI async streams historically included these fields even when 0. - # Keep those defaults in the shared path so they are not mistaken for - # caller-supplied token passthrough properties. - if ( - event_data["provider"] == "openai" - and usage_was_reported - and field - in { - "cache_read_input_tokens", - "reasoning_tokens", - } - ): - event_properties.setdefault( - property_name, event_data["usage_stats"].get(field, 0) - ) - elif value is not None and isinstance(value, int) and value > 0: - event_properties[property_name] = value + for field in optional_token_fields: + value = event_data["usage_stats"].get(field) + property_name = f"$ai_{field}" + # OpenAI async streams historically included these fields even when 0. + # Keep those defaults in the shared path so they are not mistaken for + # caller-supplied token passthrough properties. + if ( + event_data["provider"] == "openai" + and usage_was_reported + and field + in { + "cache_read_input_tokens", + "reasoning_tokens", + } + ): + event_properties.setdefault( + property_name, event_data["usage_stats"].get(field, 0) + ) + elif value is not None and isinstance(value, int) and value > 0: + event_properties[property_name] = value -def _add_streaming_usage_metadata( - event_properties: Dict[str, Any], usage: TokenUsage -) -> None: - cache_reporting_exclusive = usage.get("cache_reporting_exclusive") + cache_reporting_exclusive = event_data["usage_stats"].get( + "cache_reporting_exclusive" + ) if cache_reporting_exclusive is not None: event_properties["$ai_cache_reporting_exclusive"] = cache_reporting_exclusive # Add web search count if present (all providers) - web_search_count = usage.get("web_search_count") + web_search_count = event_data["usage_stats"].get("web_search_count") if ( web_search_count is not None and isinstance(web_search_count, int) @@ -1178,57 +1295,35 @@ def _add_streaming_usage_metadata( event_properties["$ai_web_search_count"] = web_search_count # Add raw usage metadata if present (all providers) - raw_usage = usage.get("raw_usage") + raw_usage = event_data["usage_stats"].get("raw_usage") if raw_usage is not None: # Already serialized by converters event_properties["$ai_usage"] = raw_usage + # Add stop reason if present + stop_reason = event_data.get("stop_reason") + if stop_reason is not None: + event_properties["$ai_stop_reason"] = stop_reason -def _streaming_base_properties( - ph_client: PostHogClient, - event_data: StreamingEventData, - trace_id: str, - error: Optional[BaseException], - input_tokens: Optional[int], - output_tokens: Optional[int], -) -> Dict[str, Any]: - # Build base event properties - return { - "$ai_provider": event_data["provider"], - "$ai_model": event_data["model"], - "$ai_model_parameters": get_model_params( - event_data["kwargs"], event_data.get("service_tier") - ), - **( - {"$ai_service_tier": event_data["service_tier"]} - if event_data.get("service_tier") is not None - else {} - ), - "$ai_input": with_privacy_mode( + # Handle provider-specific fields + if ( + event_data["provider"] == "openai" + and event_data["kwargs"].get("instructions") is not None + ): + event_properties["$ai_instructions"] = with_privacy_mode( ph_client, event_data["privacy_mode"], - finalize_ai_content(event_data["formatted_input"], ph_client), - ), - "$ai_output_choices": with_privacy_mode( + event_data["kwargs"]["instructions"], + ) + + # Send event to PostHog + if callable(getattr(ph_client, "capture_ai", None)): + _capture_ai_event( ph_client, - event_data["privacy_mode"], - finalize_ai_content(event_data["formatted_output"], ph_client), - ), - "$ai_http_status": (_get_http_status(error) if error is not None else 200), - **({"$ai_input_tokens": input_tokens} if input_tokens is not None else {}), - **({"$ai_output_tokens": output_tokens} if output_tokens is not None else {}), - "$ai_latency": event_data["latency"], - "$ai_trace_id": trace_id, - "$ai_base_url": str(event_data["base_url"]), - **(event_data.get("properties") or {}), - **( - { - "$ai_is_error": True, - "$ai_error": _format_ai_error( - ph_client, event_data["privacy_mode"], error - ), - } - if error is not None - else {} - ), - } + "$ai_generation", + distinct_id=_user_distinct_id(event_data.get("distinct_id")) or trace_id, + properties=event_properties, + groups=event_data.get("groups"), + personless=_user_distinct_id(event_data.get("distinct_id")) is None, + options=event_data.get("options"), + ) diff --git a/posthog/args.py b/posthog/args.py index aeaf5a1d8..674d0b670 100644 --- a/posthog/args.py +++ b/posthog/args.py @@ -51,12 +51,19 @@ class OptionalCaptureArgs(TypedDict): hidden ``/flags`` request on capture and may return different values than the ones the code branched on. disable_geoip: Whether to disable GeoIP lookup for this event. Defaults to False. + options: Capture options for this event, such as ``{"process_person_profile": False}``. + Sent as given, for PostHog to validate. An option wins over its legacy ``$`` property, + such as ``$process_person_profile``. A value that is not a dict is logged and ignored. + An identify-style event, such as ``$identify`` or ``$set``, gets + ``process_person_profile: True`` when this call leaves it unset, unless the SDK + generated its distinct ID. """ distinct_id: NotRequired[Optional[ID_TYPES]] properties: NotRequired[Optional[Dict[str, Any]]] timestamp: NotRequired[Optional[Union[datetime, str]]] uuid: NotRequired[Optional[Union[str, UUID]]] + options: NotRequired[Optional[Dict[str, Any]]] groups: NotRequired[Optional[Dict[str, str]]] flags: NotRequired[Optional["FeatureFlagEvaluations"]] send_feature_flags: NotRequired[ @@ -68,6 +75,9 @@ class OptionalCaptureArgs(TypedDict): _property_allowlist: NotRequired[ Optional[FrozenSet[str]] ] # Internal: strict allowlist applied to the fully-enriched event properties. Used by minimal $feature_flag_called events. + _capture_trace_context: NotRequired[ + bool + ] # Internal: add the active OpenTelemetry span's ids even when capture_trace_context is off. Used by capture_exception. _pinned_properties: NotRequired[ Optional["_PinnedProperties"] ] # Internal: properties fixed after super properties are merged. Used by config version 2 flag events. @@ -107,6 +117,8 @@ class OptionalSetArgs(TypedDict): it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID. disable_geoip: Whether to disable GeoIP lookup for this operation. Defaults to False. + options: Capture options for this event, sent as given. See ``OptionalCaptureArgs``. + ``process_person_profile`` is ``True`` unless this call sets it. """ distinct_id: NotRequired[Optional[ID_TYPES]] @@ -114,6 +126,7 @@ class OptionalSetArgs(TypedDict): timestamp: NotRequired[Optional[Union[datetime, str]]] uuid: NotRequired[Optional[Union[str, UUID]]] disable_geoip: NotRequired[Optional[bool]] + options: NotRequired[Optional[Dict[str, Any]]] ExcInfo = Union[ diff --git a/posthog/async_client.py b/posthog/async_client.py index 8572921d3..7401e3740 100644 --- a/posthog/async_client.py +++ b/posthog/async_client.py @@ -9,17 +9,19 @@ import threading import warnings import weakref +from dataclasses import replace from datetime import datetime, timezone -from functools import partial as _partial -from typing import AbstractSet, Any, Callable, Dict, Mapping, Optional, Union -from uuid import UUID, uuid4 +from typing import Any, Callable, Dict, Mapping, Optional, Union +from uuid import UUID from typing_extensions import Unpack from ._async_consumer import ( _STOP, _AsyncConsumer, + _AsyncLane, _invoke_callback, + _report_capture_failure, _is_processing_event, _QueuedEvent, _run_outside_processing_event, @@ -27,20 +29,39 @@ ) from ._async_request import ( _build_client, - _require_httpx, async_flags as _async_flags, async_remote_config as _async_remote_config, ) -from .args import ID_TYPES, ExceptionArg, OptionalCaptureArgs, OptionalSetArgs +from .args import ( + ID_TYPES, + ExceptionArg, + OptionalCaptureArgs, + OptionalSetArgs, + _PinnedProperties, +) from .capture_compression import ( CaptureCompression, + _resolve_capture_ai_compression, _resolve_capture_compression, ) -from .capture_mode import CaptureMode, _resolve_capture_mode +from .capture_event import ( + _build_event_defaults, + _event_options, + _EventDefaults, + _fill_event_defaults, + _merge_groups, + _resolve_event_uuid, +) +from .capture_send import _CAPTURE_AI_V1_PATH, _CAPTURE_V1_PATH from .client import ( MAX_DICT_SIZE as _MAX_DICT_SIZE, Client as _SyncClient, + _add_context_session_id, _capture_flag_events, + _context_tag_defaults, + _explicit_distinct_id, + _group_identify_distinct_id, + _positive_config_value, add_context_tags as _add_context_tags, get_identity_state as _get_identity_state, stringify_id as _stringify_id, @@ -53,6 +74,7 @@ get_code_variables_mask_url_credentials_context, get_context_device_id as _get_context_device_id, get_context_distinct_id as _get_context_distinct_id, + get_context_options as _get_context_options, get_context_session_id as _get_context_session_id, ) from .exception_utils import ( @@ -60,7 +82,9 @@ DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS, DEFAULT_CODE_VARIABLES_MASK_PATTERNS, DEFAULT_CODE_VARIABLES_MASK_URL_CREDENTIALS, + _exception_level, _get_current_otel_span_properties, + _without_reserved_exception_properties, exc_info_from_error, exception_is_already_captured, exceptions_from_error_tuple, @@ -68,7 +92,7 @@ mark_exception_as_captured, try_attach_code_variables_to_frames, ) -from .consumer import MAX_MSG_SIZE +from .consumer import AI_MAX_MSG_SIZE, MAX_MSG_SIZE from .emails import AsyncEmails, _client_emails, _validate_options from .feature_flag_evaluations import ( FeatureFlagEvaluations, @@ -85,7 +109,18 @@ _UNTYPED_FLAGS_RESPONSE_MESSAGE, normalize_flags_response, ) -from .utils import SizeLimitedDict, _normalize_timestamp, clean, system_context +from .utils import ( + SizeLimitedDict, + _is_personal_api_key, + _normalize_timestamp, + _rfc3339_timestamp, + clean, + _drop_invalid_distinct_id, + _drop_invalid_event_name, + _log_before_send_bad_return, + _log_before_send_error, + system_context, +) from .version import VERSION __all__ = ["AsyncClient", "AsyncPosthog"] @@ -96,7 +131,13 @@ class AsyncClient: ``capture()`` is a synchronous, non-blocking queue write. Use ``await capture_immediate()`` when the caller must wait for delivery. + ``capture_ai()`` and ``await capture_ai_immediate()`` do the same for AI + events, on a separate queue that posts to the AI capture endpoint. ``flush()``, ``join()``, and ``shutdown()`` are awaitable lifecycle methods. + Leaving an ``async with`` block on the client calls ``shutdown()``. + + The ``capture_ai_*``, ``privacy_mode`` and ``enable_full_ai_capture`` + options work the same way as on :class:`posthog.Client`. """ log = logging.getLogger("posthog") @@ -105,13 +146,13 @@ def __init__( self, project_api_key: str, host: Optional[str] = None, + *, debug: bool = False, max_queue_size: int = 10000, send: bool = True, on_error=None, flush_at: int = 100, flush_interval: float = 5.0, - gzip: bool = False, max_retries: int = 3, timeout: float = 15, thread: int = 1, @@ -120,6 +161,7 @@ def __init__( is_server: bool = True, historical_migration: bool = False, super_properties: Optional[dict[str, Any]] = None, + super_options: Optional[dict[str, Any]] = None, before_send=None, log_captured_exceptions: bool = False, project_root: Optional[str] = None, @@ -129,8 +171,13 @@ def __init__( code_variables_mask_url_credentials=None, code_variables_detect_secrets=None, in_app_modules: Optional[list[str]] = None, - capture_mode: Optional[Union[CaptureMode, str]] = None, capture_compression: Optional[Union[CaptureCompression, str]] = None, + capture_ai_compression: Optional[Union[CaptureCompression, str]] = None, + capture_ai_max_queue_size: int = 1000, + capture_ai_timeout: float = 30, + capture_ai_max_event_bytes: int = AI_MAX_MSG_SIZE, + privacy_mode: bool = False, + enable_full_ai_capture: bool = False, capture_trace_context: bool = False, secret_key: Optional[str] = None, personal_api_key: Optional[str] = None, @@ -145,6 +192,18 @@ def __init__( raise ValueError("flush_at must be greater than zero") if flush_interval <= 0: raise ValueError("flush_interval must be greater than zero") + capture_ai_max_queue_size = _positive_config_value( + "capture_ai_max_queue_size", capture_ai_max_queue_size, integer=True + ) + capture_ai_timeout = _positive_config_value( + "capture_ai_timeout", capture_ai_timeout + ) + capture_ai_max_event_bytes = _positive_config_value( + "capture_ai_max_event_bytes", + capture_ai_max_event_bytes, + integer=True, + maximum=AI_MAX_MSG_SIZE, + ) self.api_key = (project_api_key or "").strip() self.raw_host = normalize_host(host) @@ -152,21 +211,42 @@ def __init__( self.debug = debug self.send = send self.on_error = on_error - self.gzip = gzip self.max_retries = max(0, max_retries) self.timeout = timeout - self.disabled = disabled or not self.api_key + self.disabled = ( + disabled or not self.api_key or _is_personal_api_key(self.api_key) + ) self.disable_geoip = disable_geoip self.is_server = is_server self.historical_migration = historical_migration self.super_properties = super_properties + self.super_options = super_options self._release_id = _resolve_release_id() - self.capture_mode = _resolve_capture_mode(capture_mode) - self.capture_compression = _resolve_capture_compression( - capture_compression, gzip_fallback=gzip + self.capture_compression = _resolve_capture_compression(capture_compression) + self.capture_ai_compression = _resolve_capture_ai_compression( + capture_ai_compression ) self.capture_trace_context = capture_trace_context - self._configure_secret_key(secret_key, personal_api_key) + self.privacy_mode = privacy_mode + self.enable_full_ai_capture = enable_full_ai_capture is True + if personal_api_key is not None and secret_key is None: + warnings.warn( + "`personal_api_key` is deprecated; use `secret_key` instead.", + DeprecationWarning, + stacklevel=2, + ) + elif personal_api_key is not None and secret_key is not None: + self.log.warning( + "[FEATURE FLAGS] Both secret_key and personal_api_key were provided; " + "using secret_key." + ) + resolved_secret_key = secret_key if secret_key is not None else personal_api_key + self.secret_key = ( + resolved_secret_key.strip() + if isinstance(resolved_secret_key, str) + else resolved_secret_key + ) or None + self.personal_api_key = self.secret_key _validate_options( email_request_timeout_seconds, email_request_max_retries, migrated_from ) @@ -187,16 +267,35 @@ def __init__( self._feature_flag_evaluations_host_cache: Optional[ _FeatureFlagEvaluationsHost ] = None - self._configure_exception_capture( - log_captured_exceptions, - capture_exception_code_variables, - code_variables_mask_patterns, - code_variables_ignore_patterns, - code_variables_mask_url_credentials, - code_variables_detect_secrets, - in_app_modules, - project_root, + self.log_captured_exceptions = log_captured_exceptions + self.capture_exception_code_variables = capture_exception_code_variables + self.code_variables_mask_patterns = ( + code_variables_mask_patterns + if code_variables_mask_patterns is not None + else DEFAULT_CODE_VARIABLES_MASK_PATTERNS + ) + self.code_variables_ignore_patterns = ( + code_variables_ignore_patterns + if code_variables_ignore_patterns is not None + else DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS + ) + self.code_variables_mask_url_credentials = ( + code_variables_mask_url_credentials + if code_variables_mask_url_credentials is not None + else DEFAULT_CODE_VARIABLES_MASK_URL_CREDENTIALS + ) + self.code_variables_detect_secrets = ( + code_variables_detect_secrets + if code_variables_detect_secrets is not None + else DEFAULT_CODE_VARIABLES_DETECT_SECRETS ) + self.in_app_modules = in_app_modules + self.project_root = project_root + if self.project_root is None: + try: + self.project_root = os.getcwd() + except Exception: + self.project_root = None if before_send is not None and not callable(before_send): self.log.warning("before_send is not callable, it will be ignored") @@ -215,13 +314,35 @@ def __init__( self.log.error( "api_key is empty after trimming whitespace; check your project API key" ) + elif _is_personal_api_key(self.api_key): + self.log.error( + "api_key is a personal API key (phx_...), not a project API key; " + "PostHog is disabled. Use the project API key (phc_...)." + ) - self._queue: asyncio.Queue[Any] = asyncio.Queue(max_queue_size) + self._analytics_lane = _AsyncLane( + name="analytics", + max_queue_size=max_queue_size, + endpoint=_CAPTURE_V1_PATH, + max_msg_size=MAX_MSG_SIZE, + timeout=timeout, + capture_compression=self.capture_compression, + ) + # AI events post to their own endpoint, so multi-MB events stay off the + # analytics endpoint's smaller caps. Its workers start on the first AI + # event, so clients that never send one pay nothing. + self._ai_lane = _AsyncLane( + name="ai", + max_queue_size=capture_ai_max_queue_size, + endpoint=_CAPTURE_AI_V1_PATH, + max_msg_size=capture_ai_max_event_bytes, + timeout=capture_ai_timeout, + capture_compression=self.capture_ai_compression, + ) + self._lanes = (self._analytics_lane, self._ai_lane) self._worker_count = max(1, thread) self._flush_at = flush_at self._flush_interval = flush_interval - self._consumers: list[_AsyncConsumer] = [] - self._worker_tasks: list[asyncio.Task[None]] = [] self._immediate_callers: dict[asyncio.Task[Any], int] = {} self._inflight_operations: set[asyncio.Future[None]] = set() self._http_client: Optional[Any] = None @@ -234,69 +355,6 @@ def __init__( self._duplicate_client_registry_key: Optional[tuple[str, str]] = None self._register_duplicate_client() - def _configure_secret_key( - self, secret_key: Optional[str], personal_api_key: Optional[str] - ) -> None: - if personal_api_key is not None and secret_key is None: - warnings.warn( - "`personal_api_key` is deprecated; use `secret_key` instead.", - DeprecationWarning, - stacklevel=3, - ) - elif personal_api_key is not None and secret_key is not None: - self.log.warning( - "[FEATURE FLAGS] Both secret_key and personal_api_key were provided; " - "using secret_key." - ) - resolved_secret_key = secret_key if secret_key is not None else personal_api_key - self.secret_key = ( - resolved_secret_key.strip() - if isinstance(resolved_secret_key, str) - else resolved_secret_key - ) or None - self.personal_api_key = self.secret_key - - def _configure_exception_capture( - self, - log_captured_exceptions: bool, - capture_exception_code_variables: bool, - code_variables_mask_patterns, - code_variables_ignore_patterns, - code_variables_mask_url_credentials, - code_variables_detect_secrets, - in_app_modules: Optional[list[str]], - project_root: Optional[str], - ) -> None: - self.log_captured_exceptions = log_captured_exceptions - self.capture_exception_code_variables = capture_exception_code_variables - self.code_variables_mask_patterns = ( - code_variables_mask_patterns - if code_variables_mask_patterns is not None - else DEFAULT_CODE_VARIABLES_MASK_PATTERNS - ) - self.code_variables_ignore_patterns = ( - code_variables_ignore_patterns - if code_variables_ignore_patterns is not None - else DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS - ) - self.code_variables_mask_url_credentials = ( - code_variables_mask_url_credentials - if code_variables_mask_url_credentials is not None - else DEFAULT_CODE_VARIABLES_MASK_URL_CREDENTIALS - ) - self.code_variables_detect_secrets = ( - code_variables_detect_secrets - if code_variables_detect_secrets is not None - else DEFAULT_CODE_VARIABLES_DETECT_SECRETS - ) - self.in_app_modules = in_app_modules - self.project_root = project_root - if self.project_root is None: - try: - self.project_root = os.getcwd() - except Exception: - self.project_root = None - _emails: Optional[AsyncEmails] = None @property @@ -342,7 +400,7 @@ def _admit_email_send(self) -> Optional[Callable[[], None]]: return lambda: self._finish_inflight_operation(completion) async def __aenter__(self) -> AsyncClient: - self._ensure_workers_started() + self._ensure_workers_started(self._analytics_lane) return self async def __aexit__(self, exc_type, exc, tb) -> bool: @@ -403,44 +461,47 @@ def _get_http_client(self): self._http_client = _build_client(self.host) return self._http_client - def _new_consumer(self) -> _AsyncConsumer: - http_client = ( - self._get_http_client() if self.capture_mode == CaptureMode.V0 else None - ) + def _new_consumer(self, lane: _AsyncLane) -> _AsyncConsumer: return _AsyncConsumer( - self._queue, + lane.queue, self.api_key, host=self.host, on_error=self.on_error, process_event=self._process_event, flush_at=self._flush_at, flush_interval=self._flush_interval, - gzip=self.gzip, retries=self.max_retries, - timeout=self.timeout, + timeout=lane.timeout, historical_migration=self.historical_migration, - capture_mode=self.capture_mode, - capture_compression=self.capture_compression, - http_client=http_client, + capture_compression=lane.capture_compression, + endpoint=lane.endpoint, + max_msg_size=lane.max_msg_size, ) - def _validate_transport_available(self) -> None: - if self.capture_mode == CaptureMode.V0: - _require_httpx() - - def _ensure_workers_started(self) -> None: - if self.disabled or not self.send or self._closed or self._worker_tasks: + def _ensure_workers_started(self, lane: _AsyncLane) -> None: + if self.disabled or not self.send or self._closed or lane.worker_tasks: return self._bind_loop() for _ in range(self._worker_count): - consumer = self._new_consumer() - self._consumers.append(consumer) - self._worker_tasks.append(asyncio.create_task(consumer.run())) + consumer = self._new_consumer(lane) + lane.consumers.append(consumer) + lane.worker_tasks.append(asyncio.create_task(consumer.run())) + + def _all_worker_tasks(self) -> list[asyncio.Task[None]]: + return [task for lane in self._lanes for task in lane.worker_tasks] - def _enqueue_prepared_event(self, prepared: dict[str, Any]) -> bool: + def _enqueue_prepared_event( + self, prepared: dict[str, Any], lane: _AsyncLane, defaults: _EventDefaults + ) -> bool: if not self._accepting or self._closed: return False - queued_event = _QueuedEvent(prepared, contextvars.copy_context()) + # Shallow copy, as 7.x merged super_properties into a new dict at capture. + defaults = replace( + defaults, + property_layers=tuple(dict(layer) for layer in defaults.property_layers), + option_layers=tuple(dict(layer) for layer in defaults.option_layers), + ) + queued_event = _QueuedEvent(prepared, contextvars.copy_context(), defaults) try: running_loop = asyncio.get_running_loop() except RuntimeError: @@ -448,83 +509,66 @@ def _enqueue_prepared_event(self, prepared: dict[str, Any]) -> bool: if self._loop is None: if running_loop is not None: - self._ensure_workers_started() - self._queue.put_nowait(queued_event) + self._ensure_workers_started(lane) + lane.queue.put_nowait(queued_event) return True if running_loop is self._loop: - self._ensure_workers_started() - self._queue.put_nowait(queued_event) + self._ensure_workers_started(lane) + lane.queue.put_nowait(queued_event) return True - return self._enqueue_from_thread(self._loop, queued_event, running_loop) - - def _enqueue_from_thread( - self, - loop: asyncio.AbstractEventLoop, - queued_event: _QueuedEvent, - running_loop: Optional[asyncio.AbstractEventLoop], - ) -> bool: if running_loop is not None: raise RuntimeError("AsyncClient cannot be shared across event loops") - if self._loop_thread_id == threading.get_ident() or not loop.is_running(): + if self._loop_thread_id == threading.get_ident() or not self._loop.is_running(): raise RuntimeError("AsyncClient event loop is not running") admitted: concurrent.futures.Future[bool] = concurrent.futures.Future() - loop.call_soon_threadsafe( - _partial(self._enqueue_on_bound_loop, queued_event, admitted) - ) - return admitted.result() - - def _enqueue_on_bound_loop( - self, queued_event: _QueuedEvent, admitted: concurrent.futures.Future[bool] - ) -> None: - try: - if not self._accepting or self._closed: - admitted.set_result(False) - return - self._ensure_workers_started() - self._queue.put_nowait(queued_event) - except BaseException as error: - admitted.set_exception(error) - else: - admitted.set_result(True) - - def _normalize_uuid(self, msg: dict[str, Any]) -> str: - raw_uuid = msg.pop("uuid", None) - if raw_uuid is not None: + def enqueue_on_bound_loop() -> None: try: - normalized = str(UUID(str(raw_uuid))) - except (TypeError, ValueError, AttributeError): - self.log.error( - "Invalid UUID %r. Falling back to a generated UUID.", raw_uuid - ) + if not self._accepting or self._closed: + admitted.set_result(False) + return + self._ensure_workers_started(lane) + lane.queue.put_nowait(queued_event) + except BaseException as error: + admitted.set_exception(error) else: - msg["uuid"] = normalized - return normalized + admitted.set_result(True) + + self._loop.call_soon_threadsafe(enqueue_on_bound_loop) + return admitted.result() - normalized = str(uuid4()) + def _normalize_uuid(self, msg: dict[str, Any]) -> str: + normalized = _resolve_event_uuid(msg.pop("uuid", None)) msg["uuid"] = normalized return normalized def _prepare_event( self, msg: dict[str, Any], - disable_geoip: Optional[bool], property_allowlist=None, pinned_properties=None, ) -> tuple[Optional[dict[str, Any]], Optional[str]]: if self.disabled or not self._accepting: return None, None - msg["timestamp"] = self._event_timestamp(msg.get("timestamp")) + timestamp = msg.get("timestamp") + if timestamp is None: + timestamp = datetime.now(tz=timezone.utc) + try: + msg["timestamp"] = _normalize_timestamp(timestamp) + except ValueError: + self.log.warning( + "Invalid timestamp; it must be a datetime or an ISO 8601 string. " + "Falling back to the current UTC time." + ) + msg["timestamp"] = _rfc3339_timestamp(datetime.now(tz=timezone.utc)) sent_uuid = self._normalize_uuid(msg) - self._add_capture_metadata(msg, disable_geoip) - # After every enrichment step, so a super property never changes or adds - # config version 2 flag attribution. - if pinned_properties is not None: - msg["properties"] = pinned_properties.apply(msg["properties"]) + msg.setdefault("properties", {}) + + msg["options"] = msg.get("options") or {} if property_allowlist is not None: msg["properties"] = { key: value @@ -536,76 +580,87 @@ def _prepare_event( cleaned = clean(msg) return cleaned, sent_uuid - def _add_capture_metadata( - self, msg: dict[str, Any], disable_geoip: Optional[bool] - ) -> None: - properties = msg.setdefault("properties", {}) - properties["$lib"] = "posthog-python" - properties["$lib_version"] = VERSION - - if disable_geoip is None: - disable_geoip = self.disable_geoip - if disable_geoip: - properties["$geoip_disable"] = True - if self.super_properties: - msg["properties"] = {**properties, **self.super_properties} - if self._release_id is not None: - msg["properties"].setdefault("$release_id", self._release_id) - if self.is_server: - msg["properties"]["$is_server"] = True - - def _event_timestamp(self, value: Any) -> str: - timestamp = value - if timestamp is None: - timestamp = datetime.now(tz=timezone.utc) - try: - return _normalize_timestamp(timestamp) - except ValueError: - self.log.warning( - "Invalid timestamp %r. Falling back to the current UTC time.", - timestamp, - ) - return datetime.now(tz=timezone.utc).isoformat() + async def _process_event( + self, msg: dict[str, Any], defaults: Optional[_EventDefaults] + ) -> Optional[dict[str, Any]]: + _fill_event_defaults(msg, defaults) + processed = await self._run_before_send(msg) + if ( + processed is None + or _drop_invalid_event_name(self.log, processed) + or _drop_invalid_distinct_id(self.log, processed) + ): + return None + return processed - async def _process_event(self, msg: dict[str, Any]) -> Optional[dict[str, Any]]: + async def _run_before_send(self, msg: dict[str, Any]) -> Optional[dict[str, Any]]: if self.before_send is None: return msg original_uuid = msg["uuid"] + event_name = msg.get("event") try: result = await _invoke_callback(self.before_send, msg) if result is None: self.log.debug("event dropped by before_send callback") return None if not isinstance(result, dict): - raise TypeError("before_send must return a dict or None") + _log_before_send_bad_return(self.log, event_name, result) + return None processed = clean(result) processed["uuid"] = original_uuid return processed except Exception as error: - self.log.error("Error in before_send callback (%s)", type(error).__name__) + _log_before_send_error(self.log, event_name, error) return None + def _event_defaults( + self, + context_properties: Optional[dict[str, Any]] = None, + context_options: Optional[dict[str, Any]] = None, + personless: bool = False, + property_allowlist=None, + disable_geoip: Optional[bool] = None, + system_properties: Optional[dict[str, Any]] = None, + flag_properties: Optional[dict[str, Any]] = None, + trace_properties: Optional[dict[str, Any]] = None, + pinned_properties: Optional[_PinnedProperties] = None, + ) -> _EventDefaults: + return _build_event_defaults( + super_properties=self.super_properties, + super_options=self.super_options, + release_id=self._release_id, + context_properties=context_properties, + context_options=context_options, + personless=personless, + property_allowlist=property_allowlist, + is_server=self.is_server, + disable_geoip=self.disable_geoip, + call_disable_geoip=disable_geoip, + system_properties=system_properties, + flag_properties=flag_properties, + trace_properties=trace_properties, + library_id="posthog-python", + library_version=VERSION, + pinned_properties=pinned_properties, + ) + def _build_capture_event( self, event: str, kwargs: OptionalCaptureArgs - ) -> tuple[dict[str, Any], Optional[bool], Any, Any]: - properties = {**(kwargs.get("properties") or {}), **system_context()} - if self.capture_trace_context: - properties = {**_get_current_otel_span_properties(), **properties} - properties = _add_context_tags(properties) - assert properties is not None + ) -> tuple[dict[str, Any], Any, _EventDefaults]: + properties = dict(kwargs.get("properties") or {}) + properties = _add_context_session_id(properties) distinct_id, personless = _get_identity_state(kwargs.get("distinct_id")) - if personless and "$process_person_profile" not in properties: - properties["$process_person_profile"] = False groups = kwargs.get("groups") if groups: - properties["$groups"] = groups + _merge_groups(properties, groups) flags_snapshot = kwargs.get("flags") send_feature_flags = kwargs.get("send_feature_flags") + flag_properties = None if flags_snapshot is not None: - properties = {**flags_snapshot._get_event_properties(), **properties} + flag_properties = flags_snapshot._get_event_properties() elif send_feature_flags: warnings.warn( "AsyncClient does not support deprecated send_feature_flags. Pass a " @@ -621,35 +676,69 @@ def _build_capture_event( "distinct_id": distinct_id, "event": event, "uuid": kwargs.get("uuid"), + "options": _event_options(kwargs.get("options")), }, - kwargs.get("disable_geoip"), kwargs.get("_property_allowlist"), - kwargs.get("_pinned_properties"), + self._event_defaults( + context_properties=_context_tag_defaults(), + context_options=_get_context_options(), + personless=personless, + property_allowlist=kwargs.get("_property_allowlist"), + disable_geoip=kwargs.get("disable_geoip"), + system_properties=system_context(), + flag_properties=flag_properties, + pinned_properties=kwargs.get("_pinned_properties"), + trace_properties=( + _get_current_otel_span_properties() + if self.capture_trace_context + or kwargs.get("_capture_trace_context") + else None + ), + ), ) def capture( self, event: str, **kwargs: Unpack[OptionalCaptureArgs] ) -> Optional[str]: """Queue an event without blocking for network delivery.""" - try: - msg, disable_geoip, property_allowlist, pinned_properties = ( - self._build_capture_event(event, kwargs) - ) - prepared, sent_uuid = self._prepare_event( - msg, disable_geoip, property_allowlist, pinned_properties + return self._capture(event, self._analytics_lane, kwargs) + + def capture_ai( + self, event: str, **kwargs: Unpack[OptionalCaptureArgs] + ) -> Optional[str]: + """Queue an AI event for the AI capture endpoint without blocking. + + Takes the same arguments and returns the same value as ``capture()``. + The event uses a separate queue with a larger per-event size cap. The + payload is sent as given, with no redaction or truncation. + """ + self._log_non_ai_event(event) + return self._capture(event, self._ai_lane, kwargs) + + def _log_non_ai_event(self, event: str) -> None: + if isinstance(event, str) and not event.startswith("$ai_"): + self.log.debug( + "capture_ai called with non-AI event name %r; routing it to the AI endpoint anyway.", + event, ) + + def _capture( + self, event: str, lane: _AsyncLane, kwargs: OptionalCaptureArgs + ) -> Optional[str]: + try: + msg, property_allowlist, defaults = self._build_capture_event(event, kwargs) + prepared, sent_uuid = self._prepare_event(msg, property_allowlist) if prepared is None or sent_uuid is None: return None if not self.send: return sent_uuid - self._validate_transport_available() - if not self._enqueue_prepared_event(prepared): + if not self._enqueue_prepared_event(prepared, lane, defaults): return None self.log.debug("queued async event %s", event) return sent_uuid except asyncio.QueueFull: - self.log.warning("PostHog async capture queue is full") + self.log.warning("PostHog async %s capture queue is full", lane.name) return None except Exception as error: if self.debug: @@ -671,93 +760,74 @@ async def capture_immediate( self, event: str, **kwargs: Unpack[OptionalCaptureArgs] ) -> Optional[str]: """Capture one event and wait until its delivery attempt completes.""" - admitted = self._start_immediate_call() - if admitted is None: + return await self._capture_immediate(event, self._analytics_lane, kwargs) + + async def capture_ai_immediate( + self, event: str, **kwargs: Unpack[OptionalCaptureArgs] + ) -> Optional[str]: + """Capture one AI event and wait until its delivery attempt completes. + + Uses the AI capture endpoint and the ``capture_ai_*`` settings. + """ + self._log_non_ai_event(event) + return await self._capture_immediate(event, self._ai_lane, kwargs) + + async def _capture_immediate( + self, event: str, lane: _AsyncLane, kwargs: OptionalCaptureArgs + ) -> Optional[str]: + current = asyncio.current_task() + if current is None: # pragma: no cover - async functions always have a task + return None + if not self._accepting: return None - current, completion = admitted + completion = self._start_inflight_operation() + self._immediate_callers[current] = self._immediate_callers.get(current, 0) + 1 error_batch: list[dict[str, Any]] = [] try: - msg, disable_geoip, property_allowlist, pinned_properties = ( - self._build_capture_event(event, kwargs) - ) - prepared, sent_uuid = self._prepare_event( - msg, disable_geoip, property_allowlist, pinned_properties - ) + msg, property_allowlist, defaults = self._build_capture_event(event, kwargs) + prepared, sent_uuid = self._prepare_event(msg, property_allowlist) if prepared is None or sent_uuid is None: return None - processed = await self._process_event(prepared) + processed = await self._process_event(prepared, defaults) if processed is None: return None error_batch = [processed] if not self.send: return sent_uuid - if not await self._immediate_event_is_sendable(processed): + try: + event_size = await _serialized_event_size(processed) + except Exception: + self.log.error( + "unable to serialize immediate event for sizing, dropping" + ) + return None + if event_size > lane.max_msg_size: + self.log.error( + "Event %s (%d bytes) exceeds the %dKiB limit for %s, dropping.", + processed.get("event"), + event_size, + lane.max_msg_size // 1024, + lane.endpoint, + ) return None - consumer = self._new_consumer() + consumer = self._new_consumer(lane) await consumer.request(error_batch) return sent_uuid except Exception as error: - await self._notify_immediate_error(error, error_batch) + await _report_capture_failure( + self.on_error, self.log, error, error_batch, lane.endpoint + ) if self.debug: raise - self.log.error( - "Immediate async capture failed (%s, status=%s)", - type(error).__name__, - getattr(error, "status", None), - ) return None finally: - self._finish_immediate_call(current, completion) - - def _start_immediate_call( - self, - ) -> Optional[tuple[asyncio.Task[Any], asyncio.Future[None]]]: - current = asyncio.current_task() - if current is None: # pragma: no cover - async functions always have a task - return None - if not self._accepting: - return None - completion = self._start_inflight_operation() - self._immediate_callers[current] = self._immediate_callers.get(current, 0) + 1 - return current, completion - - def _finish_immediate_call( - self, current: asyncio.Task[Any], completion: asyncio.Future[None] - ) -> None: - remaining_calls = self._immediate_callers[current] - 1 - if remaining_calls: - self._immediate_callers[current] = remaining_calls - else: - del self._immediate_callers[current] - self._finish_inflight_operation(completion) - - async def _notify_immediate_error( - self, error: Exception, error_batch: list[dict[str, Any]] - ) -> None: - if self.on_error: - try: - await _invoke_callback(self.on_error, error, error_batch) - except Exception as callback_error: - self.log.error( - "on_error handler failed (%s)", type(callback_error).__name__ - ) - - async def _immediate_event_is_sendable(self, processed: dict[str, Any]) -> bool: - try: - event_size = await _serialized_event_size(processed) - except Exception: - self.log.error("unable to serialize immediate event for sizing, dropping") - return False - if event_size > MAX_MSG_SIZE: - self.log.error( - "Event %s (%d bytes) exceeds the %dKiB limit, dropping.", - processed.get("event"), - event_size, - MAX_MSG_SIZE // 1024, - ) - return False - return True + remaining_calls = self._immediate_callers[current] - 1 + if remaining_calls: + self._immediate_callers[current] = remaining_calls + else: + del self._immediate_callers[current] + self._finish_inflight_operation(completion) def _build_person_properties_event( self, event: str, property_key: str, kwargs: OptionalSetArgs @@ -772,6 +842,7 @@ def _build_person_properties_event( property_key: properties, "event": event, "uuid": kwargs.get("uuid"), + "options": _event_options(kwargs.get("options")), } def set(self, **kwargs: Unpack[OptionalSetArgs]) -> Optional[str]: @@ -779,7 +850,9 @@ def set(self, **kwargs: Unpack[OptionalSetArgs]) -> Optional[str]: msg = self._build_person_properties_event("$set", "$set", kwargs) if msg is None: return None - return self._enqueue_built_event(msg, kwargs.get("disable_geoip")) + return self._enqueue_built_event( + msg, kwargs.get("disable_geoip"), _get_context_options() + ) except Exception as error: if self.debug: raise @@ -791,7 +864,9 @@ def set_once(self, **kwargs: Unpack[OptionalSetArgs]) -> Optional[str]: msg = self._build_person_properties_event("$set_once", "$set_once", kwargs) if msg is None: return None - return self._enqueue_built_event(msg, kwargs.get("disable_geoip")) + return self._enqueue_built_event( + msg, kwargs.get("disable_geoip"), _get_context_options() + ) except Exception as error: if self.debug: raise @@ -807,6 +882,7 @@ def group_identify( uuid: Optional[Union[str, UUID]] = None, disable_geoip: Optional[bool] = None, distinct_id: Optional[ID_TYPES] = None, + options: Optional[Dict[str, Any]] = None, ) -> Optional[str]: try: if not _stringify_id(group_type): @@ -820,7 +896,9 @@ def group_identify( ) return None - resolved_distinct_id = _get_identity_state(distinct_id)[0] + resolved_distinct_id = _group_identify_distinct_id( + distinct_id, group_type, group_key + ) msg: dict[str, Any] = { "event": "$groupidentify", "properties": { @@ -831,11 +909,16 @@ def group_identify( "distinct_id": resolved_distinct_id, "timestamp": timestamp, "uuid": uuid, + "options": _event_options(options), } - session_id = _get_context_session_id() - if session_id: - msg["properties"]["$session_id"] = str(session_id) - return self._enqueue_built_event(msg, disable_geoip) + # No context session: this event's distinct id is not the session's + # user, and a session takes the person of its latest event. + return self._enqueue_built_event( + msg, + disable_geoip, + _get_context_options(), + context_properties=_context_tag_defaults(), + ) except Exception as error: if self.debug: raise @@ -849,14 +932,17 @@ def alias( timestamp: Optional[Union[datetime, str]] = None, uuid: Optional[str] = None, disable_geoip: Optional[bool] = None, + options: Optional[Dict[str, Any]] = None, ) -> Optional[str]: try: resolved_previous_id = _stringify_id(previous_id) if not resolved_previous_id: self.log.warning("alias() called without a previous_id, dropping event") return None - resolved_distinct_id, personless = _get_identity_state(distinct_id) - if personless: + # The alias target always comes from the caller: a context id can + # come from a client-controlled request header. + resolved_distinct_id = _explicit_distinct_id(distinct_id) + if not resolved_distinct_id: self.log.warning("alias() called without a distinct_id, dropping event") return None msg: dict[str, Any] = { @@ -868,11 +954,17 @@ def alias( "event": "$create_alias", "distinct_id": resolved_previous_id, "uuid": uuid, + "options": _event_options(options), } session_id = _get_context_session_id() if session_id: msg["properties"]["$session_id"] = str(session_id) - return self._enqueue_built_event(msg, disable_geoip) + return self._enqueue_built_event( + msg, + disable_geoip, + _get_context_options(), + context_properties=_context_tag_defaults(), + ) except Exception as error: if self.debug: raise @@ -880,27 +972,58 @@ def alias( return None def _enqueue_built_event( - self, msg: dict[str, Any], disable_geoip: Optional[bool] + self, + msg: dict[str, Any], + disable_geoip: Optional[bool], + context_options: Optional[dict[str, Any]] = None, + context_properties: Optional[dict[str, Any]] = None, ) -> Optional[str]: - prepared, sent_uuid = self._prepare_event(msg, disable_geoip) + prepared, sent_uuid = self._prepare_event(msg) if prepared is None or sent_uuid is None: return None if not self.send: return sent_uuid - self._validate_transport_available() - if not self._enqueue_prepared_event(prepared): + defaults = self._event_defaults( + context_properties=context_properties, + context_options=context_options, + disable_geoip=disable_geoip, + ) + if not self._enqueue_prepared_event(prepared, self._analytics_lane, defaults): return None return sent_uuid def capture_exception( self, exception: Optional[ExceptionArg] = None, + *, + level: Optional[str] = None, **kwargs: Unpack[OptionalCaptureArgs], ) -> Optional[str]: - """Capture an exception. This method never raises, including in debug mode.""" + """Capture an exception. This method never raises, including in debug mode. + + ``level`` sets ``$exception_level`` and defaults to ``"error"``. An unknown + value counts as unset. Reserved exception properties in ``properties``, + such as ``$exception_list`` and ``$exception_level``, are ignored. + + When OpenTelemetry is installed and a valid span is active, its trace and + span IDs are added as ``$trace_id`` and ``$span_id`` event properties, + unless the event, a context tag or ``super_properties`` sets either one. + """ try: - exc_info = self._exception_info(exception) - if exc_info is None: + if exception is not None and exception_is_already_captured(exception): + self.log.debug("Exception already captured, skipping") + return None + exc_info = ( + exc_info_from_error(exception) + if exception is not None + else sys.exc_info() + ) + if exc_info is None or exc_info == (None, None, None): + self.log.warning("No exception information available") + return None + + if exception is None and exception_is_already_captured(exc_info): + self.log.debug("Exception already captured, skipping") return None exceptions = exceptions_from_error_tuple(exc_info) @@ -911,10 +1034,47 @@ def capture_exception( ) exceptions = event["exception"]["values"] properties = { + **_without_reserved_exception_properties(kwargs.get("properties")), "$exception_list": exceptions, - **(kwargs.get("properties") or {}), + "$exception_level": _exception_level(None, level), } - self._attach_exception_code_variables(exceptions, exc_info) + context_enabled = get_capture_exception_code_variables_context() + context_mask = get_code_variables_mask_patterns_context() + context_ignore = get_code_variables_ignore_patterns_context() + context_mask_url_credentials = ( + get_code_variables_mask_url_credentials_context() + ) + context_detect_secrets = get_code_variables_detect_secrets_context() + enabled = ( + context_enabled + if context_enabled is not None + else self.capture_exception_code_variables + ) + if enabled: + try_attach_code_variables_to_frames( + exceptions, + exc_info, + mask_patterns=( + context_mask + if context_mask is not None + else self.code_variables_mask_patterns + ), + ignore_patterns=( + context_ignore + if context_ignore is not None + else self.code_variables_ignore_patterns + ), + mask_url_credentials=( + context_mask_url_credentials + if context_mask_url_credentials is not None + else self.code_variables_mask_url_credentials + ), + detect_secrets=( + context_detect_secrets + if context_detect_secrets is not None + else self.code_variables_detect_secrets + ), + ) if self.log_captured_exceptions: self.log.exception(exception, extra=kwargs) @@ -927,6 +1087,8 @@ def capture_exception( groups=kwargs.get("groups"), flags=kwargs.get("flags"), disable_geoip=kwargs.get("disable_geoip"), + options=kwargs.get("options"), + _capture_trace_context=True, ) # Mark the exception as captured to prevent duplicate captures, # including one taken from sys.exc_info() @@ -937,60 +1099,6 @@ def capture_exception( self.log.exception("Failed to capture exception: %s", error) return None - def _attach_exception_code_variables(self, exceptions, exc_info) -> None: - context_enabled = get_capture_exception_code_variables_context() - context_mask = get_code_variables_mask_patterns_context() - context_ignore = get_code_variables_ignore_patterns_context() - context_mask_url_credentials = get_code_variables_mask_url_credentials_context() - context_detect_secrets = get_code_variables_detect_secrets_context() - enabled = ( - context_enabled - if context_enabled is not None - else self.capture_exception_code_variables - ) - if enabled: - try_attach_code_variables_to_frames( - exceptions, - exc_info, - mask_patterns=( - context_mask - if context_mask is not None - else self.code_variables_mask_patterns - ), - ignore_patterns=( - context_ignore - if context_ignore is not None - else self.code_variables_ignore_patterns - ), - mask_url_credentials=( - context_mask_url_credentials - if context_mask_url_credentials is not None - else self.code_variables_mask_url_credentials - ), - detect_secrets=( - context_detect_secrets - if context_detect_secrets is not None - else self.code_variables_detect_secrets - ), - ) - - def _exception_info(self, exception: Optional[ExceptionArg]): - if exception is not None and exception_is_already_captured(exception): - self.log.debug("Exception already captured, skipping") - return None - exc_info = ( - exc_info_from_error(exception) if exception is not None else sys.exc_info() - ) - if exc_info is None or exc_info == (None, None, None): - self.log.warning("No exception information available") - return None - - if exception is None and exception_is_already_captured(exc_info): - self.log.debug("Exception already captured, skipping") - return None - - return exc_info - def _get_feature_flag_evaluations_host(self) -> _FeatureFlagEvaluationsHost: if self._feature_flag_evaluations_host_cache is None: self._feature_flag_evaluations_host_cache = _FeatureFlagEvaluationsHost( @@ -1056,7 +1164,10 @@ async def evaluate_flags( ``unresolved_flags`` is always empty. """ host = self._get_feature_flag_evaluations_host() - distinct_id, device_id = _evaluation_context_ids(distinct_id, device_id) + if distinct_id is None: + distinct_id = _get_context_distinct_id() + if device_id is None: + device_id = _get_context_device_id() if distinct_id is None or distinct_id == "" or self.disabled: return FeatureFlagEvaluations(host=host, distinct_id="", flags={}) @@ -1070,6 +1181,12 @@ async def evaluate_flags( disable_geoip=disable_geoip, ) + records: dict[str, _EvaluatedFlagRecord] = {} + request_id: Optional[str] = None + evaluated_at: Optional[int] = None + errors_while_computing = False + quota_limited = False + minimal_flag_called_events = False requested_keys = set(flag_keys) if flag_keys else None if not self._accepting: return FeatureFlagEvaluations( @@ -1079,43 +1196,12 @@ async def evaluate_flags( groups=resolved_groups, disable_geoip=disable_geoip, ) - return await self._request_flag_snapshot( - host, - distinct_id, - requested_keys, - groups=resolved_groups, - person_properties=person_properties, - group_properties=group_properties, - disable_geoip=disable_geoip, - flag_keys=flag_keys, - device_id=device_id, - ) - - async def _request_flag_snapshot( - self, - host: _FeatureFlagEvaluationsHost, - distinct_id: ID_TYPES, - requested_keys: Optional[AbstractSet[str]], - *, - groups: Mapping[str, Union[str, int]], - person_properties: Optional[Dict[str, Any]], - group_properties: Optional[Dict[str, Dict[str, Any]]], - disable_geoip: Optional[bool], - flag_keys: Optional[list[str]], - device_id: Optional[str], - ) -> FeatureFlagEvaluations: - records: dict[str, _EvaluatedFlagRecord] = {} - request_id: Optional[str] = None - evaluated_at: Optional[int] = None - errors_while_computing = False - quota_limited = False - minimal_flag_called_events = False completion = self._start_inflight_operation() try: response = await self._get_flags_decision( distinct_id, - groups=groups, + groups=resolved_groups, person_properties=person_properties, group_properties=group_properties, disable_geoip=disable_geoip, @@ -1153,7 +1239,7 @@ async def _request_flag_snapshot( host=host, distinct_id=str(distinct_id), flags=records, - groups=groups, + groups=resolved_groups, disable_geoip=disable_geoip, request_id=request_id, evaluated_at=evaluated_at, @@ -1229,40 +1315,43 @@ def _capture_feature_flag_called_if_needed( ) def _pending_queue_items(self) -> int: - return int(getattr(self._queue, "_unfinished_tasks", self._queue.qsize())) + return sum(lane.pending_items() for lane in self._lanes) def _defer_lifecycle_call(self, awaitable) -> None: task = asyncio.create_task(_run_outside_processing_event(awaitable)) self._deferred_lifecycle_tasks.add(task) task.add_done_callback(self._deferred_lifecycle_tasks.discard) - def _discard_undrainable_queue(self) -> None: + def _discard_undrainable_queue(self, lane: _AsyncLane) -> None: discarded = 0 while True: try: - self._queue.get_nowait() + lane.queue.get_nowait() except asyncio.QueueEmpty: break - self._queue.task_done() + lane.queue.task_done() discarded += 1 - orphaned = self._pending_queue_items() + orphaned = lane.pending_items() for _ in range(orphaned): - self._queue.task_done() + lane.queue.task_done() discarded += orphaned if discarded: self.log.warning( - "discarded %d async capture items because all workers exited", + "discarded %d async %s capture items because all workers exited", discarded, + lane.name, ) - async def _wait_for_queue_drain(self, deadline: Optional[float]) -> None: - live_workers = [task for task in self._worker_tasks if not task.done()] + async def _wait_for_queue_drain( + self, lane: _AsyncLane, deadline: Optional[float] + ) -> None: + live_workers = [task for task in lane.worker_tasks if not task.done()] if not live_workers: - self._discard_undrainable_queue() + self._discard_undrainable_queue(lane) return - queue_join = asyncio.create_task(self._queue.join()) + queue_join = asyncio.create_task(lane.queue.join()) async def wait_for_workers() -> None: await asyncio.wait(live_workers, return_when=asyncio.ALL_COMPLETED) @@ -1285,7 +1374,7 @@ async def wait_for_workers() -> None: await queue_join return - self._discard_undrainable_queue() + self._discard_undrainable_queue(lane) await queue_join finally: for task in (queue_join, workers_finished): @@ -1294,22 +1383,28 @@ async def wait_for_workers() -> None: await asyncio.gather(queue_join, workers_finished, return_exceptions=True) async def flush(self, timeout_seconds: Optional[float] = 10) -> None: - if asyncio.current_task() in self._worker_tasks or _is_processing_event(): + if asyncio.current_task() in self._all_worker_tasks() or _is_processing_event(): self._defer_lifecycle_call(self.flush(timeout_seconds)) return if not self.send or self.disabled or self._pending_queue_items() == 0: return - self._ensure_workers_started() + pending_lanes = [lane for lane in self._lanes if lane.pending_items()] + for lane in pending_lanes: + self._ensure_workers_started(lane) deadline = ( None if timeout_seconds is None else asyncio.get_running_loop().time() + timeout_seconds ) try: - for consumer in self._consumers: - consumer.request_flush() - - await self._wait_for_queue_drain(deadline) + # Wake every lane before waiting on any, so one lane's partial + # batch does not wait out its flush_interval behind the other. + for lane in pending_lanes: + for consumer in lane.consumers: + consumer.request_flush() + + for lane in pending_lanes: + await self._wait_for_queue_drain(lane, deadline) except asyncio.TimeoutError: self.log.warning( "flush timed out after %s seconds with %s items pending", @@ -1326,7 +1421,7 @@ async def _close_transport(self) -> None: async def shutdown(self) -> None: current = asyncio.current_task() if ( - current in self._worker_tasks + current in self._all_worker_tasks() or current in self._immediate_callers or _is_processing_event() ): @@ -1341,7 +1436,13 @@ async def shutdown(self) -> None: self._accepting = False errors: list[Exception] = [] - await self._wait_for_inflight_operations() + pending_operations = [ + completion + for completion in self._inflight_operations + if not completion.done() + ] + if pending_operations: + await asyncio.gather(*pending_operations, return_exceptions=True) try: await self.flush(timeout_seconds=None) @@ -1349,58 +1450,46 @@ async def shutdown(self) -> None: self.log.exception("Failed to flush async capture queue") errors.append(error) - await self._stop_workers(errors) - - await self._close_resources(errors) + try: + for lane in self._lanes: + live_workers = [t for t in lane.worker_tasks if not t.done()] + for _ in live_workers: + await lane.queue.put(_STOP) + worker_tasks = self._all_worker_tasks() + if worker_tasks: + await asyncio.gather(*worker_tasks, return_exceptions=True) + except Exception as error: + self.log.exception("Failed to stop async capture workers") + errors.append(error) + finally: + for lane in self._lanes: + lane.worker_tasks.clear() + lane.consumers.clear() - self.distinct_ids_feature_flags_reported.clear() - self._experiment_exposures_reported.clear() - self._closed = True - if errors and self.debug: - raise errors[0] + try: + await self._close_transport() + except Exception as error: + self.log.exception("Failed to close async capture transport") + errors.append(error) - async def _close_resources(self, errors: list[Exception]) -> None: - try: - await self._close_transport() - except Exception as error: - self.log.exception("Failed to close async capture transport") - errors.append(error) + if self._emails is not None: + try: + await self._emails.aclose() + except Exception as error: + self.log.exception("Failed to close the async email transport") + errors.append(error) - if self._emails is not None: try: - await self._emails.aclose() + self._unregister_duplicate_client() except Exception as error: - self.log.exception("Failed to close the async email transport") + self.log.exception("Failed to unregister async client") errors.append(error) - try: - self._unregister_duplicate_client() - except Exception as error: - self.log.exception("Failed to unregister async client") - errors.append(error) - - async def _stop_workers(self, errors: list[Exception]) -> None: - try: - live_workers = [task for task in self._worker_tasks if not task.done()] - for _ in live_workers: - await self._queue.put(_STOP) - if self._worker_tasks: - await asyncio.gather(*self._worker_tasks, return_exceptions=True) - except Exception as error: - self.log.exception("Failed to stop async capture workers") - errors.append(error) - finally: - self._worker_tasks.clear() - self._consumers.clear() - - async def _wait_for_inflight_operations(self) -> None: - pending_operations = [ - completion - for completion in self._inflight_operations - if not completion.done() - ] - if pending_operations: - await asyncio.gather(*pending_operations, return_exceptions=True) + self.distinct_ids_feature_flags_reported.clear() + self._experiment_exposures_reported.clear() + self._closed = True + if errors and self.debug: + raise errors[0] async def join(self) -> None: await self.shutdown() @@ -1410,13 +1499,3 @@ class AsyncPosthog(AsyncClient): """Customer-facing name for :class:`AsyncClient`.""" pass - - -def _evaluation_context_ids( - distinct_id: Optional[ID_TYPES], device_id: Optional[str] -) -> tuple[Optional[ID_TYPES], Optional[str]]: - if distinct_id is None: - distinct_id = _get_context_distinct_id() - if device_id is None: - device_id = _get_context_device_id() - return distinct_id, device_id diff --git a/posthog/capture_compression.py b/posthog/capture_compression.py index 41e3d8e1d..035cee26c 100644 --- a/posthog/capture_compression.py +++ b/posthog/capture_compression.py @@ -19,10 +19,9 @@ class CaptureCompression(str, Enum): - """Selects the request-body compression for capture-v1 uploads. + """Selects the request-body compression for capture uploads. - Only honored when ``capture_mode`` is ``V1``; the legacy ``/batch/`` path - keeps using its own ``gzip`` flag. ``NONE`` sends the body uncompressed. + ``NONE`` sends the body uncompressed. ``GZIP`` and ``DEFLATE`` (zlib, RFC 1950) are both stdlib / zero-dependency; ``ZSTD`` is faster and compresses better but needs the optional zstandard package (``pip install posthog[zstd]``) until stdlib support lands in @@ -61,6 +60,7 @@ def _zstd_available() -> bool: def _coerce_explicit( value: Union[CaptureCompression, str], + name: str = "capture_compression", ) -> CaptureCompression: """Normalize an explicitly-supplied compression to a ``CaptureCompression``. @@ -75,22 +75,19 @@ def _coerce_explicit( if resolved is not None: return resolved raise ValueError( - f"invalid capture_compression {value!r}; expected a CaptureCompression " + f"invalid {name} {value!r}; expected a CaptureCompression " f"or one of {sorted(_ALIASES)}" ) def _resolve_capture_compression( capture_compression: Optional[Union[CaptureCompression, str]] = None, - *, - gzip_fallback: bool = False, ) -> CaptureCompression: - """Resolve the effective v1 compression. + """Resolve the effective capture compression. Precedence: explicit ``capture_compression`` argument > - ``POSTHOG_CAPTURE_COMPRESSION`` env var > the legacy ``gzip`` flag - (``GZIP`` when set) > ``NONE``. An unrecognized env value logs a warning and - falls back to the ``gzip`` flag, so a typo never silently changes encoding. + ``POSTHOG_CAPTURE_COMPRESSION`` env var > ``NONE``. An unrecognized env + value logs a warning and falls back to ``NONE``. ``ZSTD`` requires the optional zstandard package: explicitly requesting it without the package raises ``ValueError`` (programming error, fail loud), @@ -106,7 +103,7 @@ def _resolve_capture_compression( ) return resolved - fallback = CaptureCompression.GZIP if gzip_fallback else CaptureCompression.NONE + fallback = CaptureCompression.NONE return _resolve_env_compression(fallback) @@ -136,3 +133,22 @@ def _resolve_env_compression(fallback: CaptureCompression) -> CaptureCompression ) return fallback return env_resolved + + +def _resolve_capture_ai_compression( + capture_ai_compression: Optional[Union[CaptureCompression, str]] = None, +) -> CaptureCompression: + """Resolve the AI lane's request-body compression. + + Explicit argument only, defaulting to ``NONE``. ``POSTHOG_CAPTURE_COMPRESSION`` + does not apply, so changing analytics compression never changes AI uploads. + """ + if capture_ai_compression is None: + return CaptureCompression.NONE + resolved = _coerce_explicit(capture_ai_compression, "capture_ai_compression") + if resolved is CaptureCompression.ZSTD and not _zstd_available(): + raise ValueError( + "capture_ai_compression 'zstd' requires the zstandard package; " + "install posthog[zstd]" + ) + return resolved diff --git a/posthog/capture_event.py b/posthog/capture_event.py new file mode 100644 index 000000000..9d8886305 --- /dev/null +++ b/posthog/capture_event.py @@ -0,0 +1,461 @@ +"""Event shaping for the capture v1 wire protocol. + +Transforms a legacy-shaped queued message into a v1 wire event and assembles +the batch envelope. :mod:`posthog.capture_send` posts the result. + +The v1 contract (see ``rust/capture/src/v1/analytics/types.rs``) differs from +the legacy queued-message shape in a few load-bearing ways that this module +encodes: + +- An ``options`` object carries per-event processing options. Options the + caller sets are sent as given, for PostHog to validate. Four legacy ``$`` + properties fill the matching option when the caller left it unset, and are + always removed from ``properties``. +- ``$set``/``$set_once`` have no top-level form in v1; the server reads them + from ``properties``. The legacy ``set()``/``set_once()`` builders emit them at + the top level, so they are relocated into ``properties`` here. +- ``$lib``/``$lib_version`` are sent as they are at send time. The SDK fills + them as a pair below every other layer, and ``before_send`` can change or + remove them. The ``PostHog-Sdk-Info`` header is only a server-side fallback + for events that don't name their library. +""" + +import logging +import re +from collections.abc import Collection, Mapping +from dataclasses import dataclass +from datetime import datetime, timezone +from typing import TYPE_CHECKING, Any, Optional +from uuid import UUID + +from posthog.utils import _normalize_timestamp, _rfc3339_timestamp, _uuid7 +from posthog.utils import clean as _clean + +if TYPE_CHECKING: + from posthog.args import _PinnedProperties + +log = logging.getLogger("posthog") + +# Sentinel properties lifted to top-level string fields on the event. +_TOPLEVEL_SENTINELS: tuple[tuple[str, str], ...] = ( + ("$session_id", "session_id"), + ("$window_id", "window_id"), +) + +# Top-level legacy keys relocated into properties (v1 has no top-level form). +_RELOCATE_TO_PROPERTIES = ("$set", "$set_once") + +# Properties that defaults fill one level deep when both values are dicts. +_NESTED_FILL_PROPERTIES = frozenset({"$set", "$set_once", "$groups", "$group_set"}) + +# The library identity pair. Only a non-empty string counts as set. +_LIBRARY_PROPERTIES = ("$lib", "$lib_version") + +# Legacy properties and the option each one fills. The order matches posthog-rs +# and posthog-go. +_LEGACY_OPTION_PROPERTIES: tuple[tuple[str, str], ...] = ( + ("$cookieless_mode", "cookieless_mode"), + ("$ignore_sent_at", "disable_skew_correction"), + ("$product_tour_id", "product_tour_id"), + ("$process_person_profile", "process_person_profile"), +) + +# Events that change a person or group. PostHog drops or ignores them when +# person processing is off, so they default it on (see +# _default_identify_style_person_processing). +_IDENTIFY_STYLE_EVENTS = ( + "$identify", + "$create_alias", + "$merge_dangerously", + "$groupidentify", + "$set", + "$set_once", +) + +# The uuid forms Go's uuid.Validate accepts. Python's UUID() also accepts +# misplaced hyphens and a bare "uuid:" prefix, which other SDKs reject. +_EVENT_UUID_PATTERN = re.compile( + r"(?:urn:uuid:)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" + r"|\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\}" + r"|[0-9a-f]{32}", + re.IGNORECASE, +) + + +def _canonical_event_uuid(value: Any) -> Optional[str]: + """Return the canonical form of a caller's event uuid, or None if invalid. + + Capture keys per-event results by the canonical lowercase hyphenated form, + so a uuid sent in any other form would never match its result. + """ + if isinstance(value, UUID): + return str(value) + if not isinstance(value, str) or not _EVENT_UUID_PATTERN.fullmatch(value): + return None + return str(UUID(value.lower())) + + +def _resolve_event_uuid(value: Any) -> str: + """Return the canonical form of a caller's event uuid, or a generated one. + + A missing or empty uuid is generated silently. An invalid one is replaced + and logs one warning. The warning names the rule and not the value, + because callers can put their own data in the uuid field. + """ + if value is not None and value != "": + canonical = _canonical_event_uuid(value) + if canonical is not None: + return canonical + log.warning( + "Event uuid is not a valid UUID string or uuid.UUID. " + "Sending the event with a generated UUID." + ) + return str(_uuid7()) + + +def _json_type_name(value: Any) -> str: + """Name a value's JSON type, the same names posthog-go and posthog-rs log.""" + if isinstance(value, bool): + return "bool" + if isinstance(value, (int, float)): + return "number" + if isinstance(value, (list, tuple)): + return "array" + if isinstance(value, Mapping): + return "object" + return type(value).__name__ + + +def _event_options(value: Any) -> dict[str, Any]: + """Return a copy of a caller's ``options``, or ``{}`` when it is not a dict.""" + if value is None: + return {} + if not isinstance(value, dict): + log.error( + "options must be a dict, got %s. Sending the event without them.", + type(value).__name__, + ) + return {} + return dict(value) + + +@dataclass(frozen=True) +class _EventDefaults: + """Per-call, context, global and SDK-derived values for one event, highest layer first. + + They fill in before ``before_send``, so the hook sees them and can change + or remove them. The event's own values win over every default. + """ + + property_layers: tuple[Mapping[str, Any], ...] = () + option_layers: tuple[Mapping[str, Any], ...] = () + property_allowlist: Optional[Collection[str]] = None + trace_properties: Optional[Mapping[str, Any]] = None + library: Optional[tuple[str, str]] = None + pinned_properties: Optional["_PinnedProperties"] = None + personless: bool = False + + +def _is_library_value(value: Any) -> bool: + """Whether ``value`` sets ``$lib`` or ``$lib_version``: a non-empty string.""" + return isinstance(value, str) and value != "" + + +def _build_event_defaults( + *, + super_properties: Optional[Mapping[str, Any]], + super_options: Any, + release_id: Optional[str], + context_properties: Optional[Mapping[str, Any]] = None, + context_options: Optional[Mapping[str, Any]] = None, + personless: bool = False, + property_allowlist: Optional[Collection[str]] = None, + is_server: bool = False, + disable_geoip: bool = False, + call_disable_geoip: Optional[bool] = None, + system_properties: Optional[Mapping[str, Any]] = None, + flag_properties: Optional[Mapping[str, Any]] = None, + trace_properties: Optional[Mapping[str, Any]] = None, + library_id: str, + library_version: str, + pinned_properties: Optional["_PinnedProperties"] = None, +) -> _EventDefaults: + """Order the layers: per-call arguments, context, global, then SDK values. + + ``disable_geoip`` is the client setting, an SDK value. ``call_disable_geoip`` + is the argument of one call: it is a value of that event, so only the + event's own ``$geoip_disable`` property beats it. ``flag_properties`` (the + ``$feature/*`` and ``$active_feature_flags`` values from ``flags`` or + ``send_feature_flags``) are SDK values, so context and super properties + beat them. ``trace_properties`` (``$trace_id`` and ``$span_id`` from the + active OpenTelemetry span) are SDK values that fill as a pair. + ``library_id`` and ``library_version`` are the SDK's own ``$lib`` and + ``$lib_version``. They fill as a pair below every other layer. + ``pinned_properties`` is config version 2 flag attribution that no layer + may change or add to; it applies after every layer. + ``personless`` means the SDK generated the event's distinct ID. It adds + ``process_person_profile: False`` as the lowest option layer. + """ + call_properties = ( + {} if call_disable_geoip is None else {"$geoip_disable": call_disable_geoip} + ) + # A value in the event, the context or super properties wins over every + # value the SDK adds, including `$is_server` and `$geoip_disable`. + sdk_properties = {**(flag_properties or {}), **(system_properties or {})} + if release_id is not None: + sdk_properties["$release_id"] = release_id + if is_server: + sdk_properties["$is_server"] = True + if disable_geoip: + sdk_properties["$geoip_disable"] = True + return _EventDefaults( + property_layers=( + call_properties, + context_properties or {}, + super_properties or {}, + sdk_properties, + ), + option_layers=( + context_options or {}, + _event_options(super_options), + {"process_person_profile": False} if personless else {}, + ), + property_allowlist=property_allowlist, + trace_properties=trace_properties, + library=(library_id, library_version), + pinned_properties=pinned_properties, + personless=personless, + ) + + +def _fill_event_defaults( + msg: dict[str, Any], defaults: Optional[_EventDefaults] +) -> None: + """Fill the keys an event left unset from ``defaults``, layer by layer. + + A property is unset only when its key is missing, except ``$lib`` and + ``$lib_version``, which are unset unless they hold a non-empty string. An + option is unset when it is missing or ``None``, the same rule hoisting + uses. ``$set``, ``$set_once``, ``$groups`` and ``$group_set`` fill one + level deep when the event's value and the default are both dicts. + ``trace_properties`` fill last, and only when the event and every layer + leave all their keys unset. The SDK's ``library`` fills after every layer. + An identify-style event first resolves ``process_person_profile`` from the + call alone, so no layer can turn person processing off for it. Once its + option is set, its ``$process_person_profile`` property is removed. + """ + _default_identify_style_person_processing( + msg, defaults is not None and defaults.personless + ) + if defaults is None: + return + allowlist = defaults.property_allowlist + properties = msg.get("properties") + if not isinstance(properties, dict): + properties = {} + msg["properties"] = properties + for property_layer in defaults.property_layers: + for key, value in property_layer.items(): + if allowlist is not None and key not in allowlist: + continue + if key not in properties or ( + key in _LIBRARY_PROPERTIES + and _is_library_value(value) + and not _is_library_value(properties[key]) + ): + properties[key] = _clean(value) + continue + existing = properties[key] + if ( + key in _NESTED_FILL_PROPERTIES + and isinstance(existing, dict) + and isinstance(value, Mapping) + ): + properties[key] = {**_clean(dict(value)), **existing} + # A trace id and a span id from different spans would point at no real span, + # so a value for either key from any layer keeps out both of the SDK's ids. + trace_properties = defaults.trace_properties or {} + if not any(key in properties for key in trace_properties): + for key, value in trace_properties.items(): + if allowlist is None or key in allowlist: + properties[key] = _clean(value) + if defaults.library is not None: + _fill_library(properties, defaults.library, allowlist) + if defaults.pinned_properties is not None: + # After every layer, so a context tag or super property never changes + # or adds config version 2 flag attribution. The allowlist still wins. + properties = defaults.pinned_properties.apply(properties) + if allowlist is not None: + properties = {k: v for k, v in properties.items() if k in allowlist} + msg["properties"] = properties + options = _event_options(msg.get("options")) + for option_layer in defaults.option_layers: + for key, value in option_layer.items(): + if options.get(key) is None: + options[key] = _clean(value) + msg["options"] = options + # The option beats this property at serialization anyway. Dropping it now + # shows before_send one value, and a hook that drops options cannot send a + # layered legacy False. + if ( + msg.get("event") in _IDENTIFY_STYLE_EVENTS + and options.get("process_person_profile") is not None + ): + msg["properties"].pop("$process_person_profile", None) + + +def _default_identify_style_person_processing( + msg: dict[str, Any], personless: bool +) -> None: + """Resolve ``process_person_profile`` for an identify-style event from the call. + + Only the call's own values count, so it runs before any layer fills. A + non-null option is kept. Else a non-null ``$process_person_profile`` + property moves into the option. Else the option is ``True``, unless the + SDK generated the distinct ID, which keeps the personless ``False``. + """ + if msg.get("event") not in _IDENTIFY_STYLE_EVENTS: + return + options = _event_options(msg.get("options")) + if options.get("process_person_profile") is not None: + return + properties = msg.get("properties") + if ( + isinstance(properties, dict) + and properties.get("$process_person_profile") is not None + ): + options["process_person_profile"] = properties.pop("$process_person_profile") + elif personless: + return + else: + options["process_person_profile"] = True + msg["options"] = options + + +def _fill_library( + properties: dict[str, Any], + library: tuple[str, str], + allowlist: Optional[Collection[str]], +) -> None: + """Fill the SDK's ``$lib`` and ``$lib_version`` as a pair. + + With no ``$lib`` set, both are filled, replacing a lone ``$lib_version``. + A ``$lib`` naming this SDK with no ``$lib_version`` gets the SDK version. + A ``$lib`` naming another library keeps whatever ``$lib_version`` it has, + because the SDK version would misdescribe it. + """ + library_id, library_version = library + if not _is_library_value(properties.get("$lib")): + fill = {"$lib": library_id, "$lib_version": library_version} + elif properties["$lib"] == library_id and not _is_library_value( + properties.get("$lib_version") + ): + fill = {"$lib_version": library_version} + else: + return + for key, value in fill.items(): + if allowlist is None or key in allowlist: + properties[key] = value + + +def _merge_groups(properties: dict[str, Any], groups: Mapping[str, Any]) -> None: + """Merge typed ``groups`` into the ``$groups`` property; ``groups`` wins key by key.""" + existing = properties.get("$groups") + if isinstance(existing, dict): + properties["$groups"] = {**existing, **groups} + else: + properties["$groups"] = dict(groups) + + +def _v1_timestamp(timestamp: Any) -> str: + """Return a UTC RFC3339 timestamp string. + + Messages off the queue already carry a UTC ISO-8601 string (``_enqueue`` + normalizes canonical datetimes), so that is passed through. A ``datetime`` + is normalized to UTC and serialized; a missing value defaults to now in UTC. + The v1 server parses strictly with ``DateTime::parse_from_rfc3339`` and + rejects naive timestamps. + """ + if timestamp is None: + return _rfc3339_timestamp(datetime.now(timezone.utc)) + return _normalize_timestamp(timestamp) + + +def _to_v1_event(msg: dict) -> dict: + """Transform a legacy-shaped queued message into a v1 wire event. + + Pure: the input ``msg`` is not mutated (a fresh ``properties`` dict is + built), so it remains safe to keep the original for retries or callbacks. + """ + properties = dict(msg.get("properties") or {}) + + # Relocate top-level $set/$set_once into properties; v1 has no top-level + # form. The top-level value comes from the set() or set_once() call, so it + # wins key by key over a $set in properties, as ingestion merges them. + for key in _RELOCATE_TO_PROPERTIES: + top_val = msg.get(key) + if top_val is None: + continue + existing = properties.get(key) + if isinstance(top_val, dict) and isinstance(existing, dict): + properties[key] = {**existing, **top_val} + else: + properties[key] = top_val + + options = _event_options(msg.get("options")) + for prop_key, option_key in _LEGACY_OPTION_PROPERTIES: + if prop_key not in properties: + continue + legacy = properties.pop(prop_key) + # A null option counts as unset, so the legacy value fills it. + if options.get(option_key) is None: + options[option_key] = legacy + + top_level: dict[str, str] = {} + for prop_key, field_name in _TOPLEVEL_SENTINELS: + if prop_key not in properties: + continue + # Always removed. A non-string value would fail the whole batch, so it + # is dropped. None counts as unset and drops silently. + value = properties.pop(prop_key) + if isinstance(value, str): + top_level[field_name] = value + elif value is not None: + log.warning( + "dropping %s: a %s value is not a string", + prop_key, + _json_type_name(value), + ) + + event = { + "event": msg["event"], + "uuid": msg["uuid"], + "distinct_id": msg["distinct_id"], + "timestamp": _v1_timestamp(msg.get("timestamp")), + # Always a dict so it serializes as "{}" rather than null when empty. + "options": options, + "properties": properties, + } + event.update(top_level) + return event + + +def _build_v1_batch_body( + events: list[dict], + historical_migration: bool = False, + created_at: Optional[str] = None, +) -> dict: + """Assemble the v1 batch envelope. + + Carries no ``api_key`` (Bearer auth) and no ``sent_at``. + ``historical_migration`` is omitted when False (the server defaults it). + ``created_at`` defaults to now in UTC; :func:`_send_v1_batch` passes a value + hoisted once so it stays stable across retry attempts. + """ + body: dict[str, Any] = { + "created_at": created_at or _rfc3339_timestamp(datetime.now(timezone.utc)), + "batch": events, + } + if historical_migration: + body["historical_migration"] = True + return body diff --git a/posthog/capture_mode.py b/posthog/capture_mode.py deleted file mode 100644 index 7ea3696f2..000000000 --- a/posthog/capture_mode.py +++ /dev/null @@ -1,84 +0,0 @@ -import logging -import os -from enum import Enum -from typing import Optional, Union - -__all__ = ["CAPTURE_MODE_ENV_VAR", "CaptureMode"] - -log = logging.getLogger("posthog") - -CAPTURE_MODE_ENV_VAR = "POSTHOG_CAPTURE_MODE" - - -class CaptureMode(str, Enum): - """Selects the capture wire protocol used for event ingestion. - - ``V0`` is the legacy ``POST /batch/`` endpoint and the default, so upgrading - is transparent to existing callers. ``V1`` opts into - ``POST /i/v1/analytics/events`` (Bearer auth, per-event results, partial - retry). Inheriting from ``str`` keeps the members directly comparable to and - serializable as their ``"v0"`` / ``"v1"`` values. - """ - - V0 = "v0" - V1 = "v1" - - -# Accepted spellings for both the explicit kwarg and the env var. Aliases mirror -# the posthog-go naming (``legacy`` / ``analytics_v1``) so the two SDKs are -# configured with the same vocabulary. -_ALIASES: dict[str, CaptureMode] = { - "v0": CaptureMode.V0, - "legacy": CaptureMode.V0, - "v1": CaptureMode.V1, - "analytics_v1": CaptureMode.V1, -} - - -def _coerce_explicit(value: Union[CaptureMode, str]) -> CaptureMode: - """Normalize an explicitly-supplied capture mode to a ``CaptureMode``. - - Accepts a ``CaptureMode`` or one of the string aliases. An explicit but - unrecognized value is a programming error, so it raises ``ValueError`` rather - than silently defaulting (unlike the env var, which is operator-supplied and - defaults defensively). - """ - if isinstance(value, CaptureMode): - return value - if isinstance(value, str): - resolved = _ALIASES.get(value.strip().lower()) - if resolved is not None: - return resolved - raise ValueError( - f"invalid capture_mode {value!r}; expected a CaptureMode or one of " - f"{sorted(_ALIASES)}" - ) - - -def _resolve_capture_mode( - capture_mode: Optional[Union[CaptureMode, str]] = None, -) -> CaptureMode: - """Resolve the effective capture mode. - - Precedence: explicit ``capture_mode`` argument > ``POSTHOG_CAPTURE_MODE`` env - var > ``CaptureMode.V0``. An unrecognized env value logs a warning and falls - back to ``V0`` so a typo never silently flips the wire protocol. - """ - if capture_mode is not None: - return _coerce_explicit(capture_mode) - - raw = os.environ.get(CAPTURE_MODE_ENV_VAR) - if raw is None or raw.strip() == "": - return CaptureMode.V0 - - resolved = _ALIASES.get(raw.strip().lower()) - if resolved is None: - log.warning( - "Unrecognized %s=%r; falling back to %s. Expected one of %s.", - CAPTURE_MODE_ENV_VAR, - raw, - CaptureMode.V0.value, - sorted(_ALIASES), - ) - return CaptureMode.V0 - return resolved diff --git a/posthog/capture_send.py b/posthog/capture_send.py new file mode 100644 index 000000000..95815d10c --- /dev/null +++ b/posthog/capture_send.py @@ -0,0 +1,684 @@ +"""Transport for the capture v1 wire protocol. + +This module sends batches to the capture v1 endpoints +(``POST /i/v1/analytics/events`` and ``POST /i/v1/ai/events``, which share one +wire contract): a single HTTP attempt, response parsing, and the partial-retry +send loop. :mod:`posthog.capture_event` builds the events and batch envelope. + +The response is per-event: a 200 carries a ``results`` map keyed by event uuid, +each tagged ``ok``/``warning`` (terminal-success), ``drop`` (terminal-failure), +or ``retry``. :func:`_send_v1_batch` resends only the ``retry`` events on the next +attempt, holding the ``PostHog-Request-Id`` and batch ``created_at`` stable +across attempts while incrementing ``PostHog-Attempt``. ``ok``/``warning``/absent +events succeed; ``drop`` and retry-exhaustion are carried on the +:class:`CaptureError` raised on batch-level/terminal failure, so the consumer's +existing ``on_error(exc, batch)`` path surfaces them unchanged (no per-event +logging of its own). Capture keeps the first event for each uuid in a request; +a result's ``duplicates_dropped`` count reports the later copies as drops with +reason ``duplicate_event_uuid``. + +Request bodies are optionally compressed per :class:`~posthog.capture_compression.CaptureCompression` +(``gzip`` or zlib-wrapped ``deflate``), advertised via ``Content-Encoding``. +""" + +import json +import logging +import random +import time +import zlib +from dataclasses import dataclass, field +from datetime import datetime, timezone +from email.utils import parsedate_to_datetime +from gzip import GzipFile +from io import BytesIO +from typing import TYPE_CHECKING, NamedTuple, Optional, Sequence +from urllib.parse import urljoin, urlsplit +from uuid import UUID + +from requests.exceptions import RequestException +from requests.models import PreparedRequest + +from posthog.capture_compression import CaptureCompression, _zstandard +from posthog.capture_event import _build_v1_batch_body, _to_v1_event +from posthog.request import ( + DatetimeSerializer, + USER_AGENT, + APIError, + _get_capture_session, + normalize_host, +) +from posthog.utils import _rfc3339_timestamp, _uuid7, remove_trailing_slash + +if TYPE_CHECKING: + import requests + +log = logging.getLogger("posthog") + +# Only the error types are public API: they reach user code through `on_error` +# callbacks, so callers may want to catch/inspect them. Everything else is +# submitter plumbing. +__all__ = ["CaptureDroppedEvent", "CaptureError", "CaptureEventResult"] + +_CAPTURE_V1_PATH = "/i/v1/analytics/events" +_CAPTURE_AI_V1_PATH = "/i/v1/ai/events" + +# Required request/response headers for the v1 endpoint. Defined here as the +# single source of truth; the transport layer builds requests from them. +_HEADER_SDK_INFO = "PostHog-Sdk-Info" +_HEADER_ATTEMPT = "PostHog-Attempt" +_HEADER_REQUEST_ID = "PostHog-Request-Id" +_HEADER_REQUEST_TIMESTAMP = "PostHog-Request-Timestamp" + +# Per-event result codes the backend emits (rust EventResult). `ok`/`warning` +# are terminal-success; `drop` terminal-failure; `retry` is safe to resend. +_RESULT_OK = "ok" +_RESULT_WARNING = "warning" +_RESULT_DROP = "drop" +_RESULT_RETRY = "retry" + +# Drop reason for a later copy of a uuid that capture discarded in favor of the first. +_DUPLICATE_EVENT_UUID = "duplicate_event_uuid" + +# HTTP status classification. 404 and 429 can come from a proxy in front of capture. +_RETRYABLE_STATUSES = frozenset({404, 408, 429, 500, 502, 503, 504}) +# Only these keep the method and body, so a resent batch is unchanged. +_REDIRECT_STATUSES = frozenset({307, 308}) +_MAX_REDIRECTS = 5 +_TERMINAL_STATUSES = frozenset({400, 401, 402, 413, 415}) + +# Single ceiling (seconds) for the retry backoff: caps the exponential schedule +# and clamps a server ``Retry-After`` to the same value. Keeps the max retry +# wait bounded (a hostile/buggy header can't park the consumer thread) and +# unifies the default with posthog-go/posthog-rs (all 30s). +_MAX_BACKOFF_SECONDS = 30 + +# First retry delay; it doubles per attempt up to `_MAX_BACKOFF_SECONDS`. Matches +# posthog-go. +_BACKOFF_BASE_SECONDS = 0.1 + +# Spread each backoff by up to a quarter, so clients refused together do not +# return together. +_BACKOFF_JITTER = 0.25 + + +@dataclass(frozen=True) +class CaptureEventResult: + """One event's verdict from a 2xx capture response. + + ``result`` is ``ok``, ``warning``, ``drop`` or ``retry``, or a value newer + than this SDK, which counts as success. ``details`` is the server's reason + tag, such as ``llm_events_over_quota``. + """ + + result: Optional[str] + details: Optional[str] = None + + +class CaptureDroppedEvent(NamedTuple): + """One event capture dropped in a 2xx response. + + A ``(uuid, details)`` tuple with named fields. ``details`` is the server's + reason tag, such as ``llm_events_over_quota``. + """ + + uuid: str + details: Optional[str] = None + + +@dataclass +class _V1ParsedResponse: + """Classified outcome of one v1 HTTP attempt. + + ``is_success`` is the 2xx classification. On success ``results`` holds the + per-uuid directives (``None``/``malformed=True`` when the body could not be + parsed — treated as terminal so a bad success never loops forever). On a + non-2xx, ``error_message`` is the best-effort human-readable detail. + ``duplicates_dropped`` maps a uuid to the number of its later copies + capture dropped; it is empty when no result carries the field. + """ + + status_code: int + is_success: bool + retry_after: Optional[float] = None + results: Optional[dict[str, CaptureEventResult]] = None + duplicates_dropped: dict[str, int] = field(default_factory=dict) + malformed: bool = False + error_message: str = "" + + +class CaptureError(APIError): + """A capture batch that was not fully delivered. + + Passed to ``on_error`` with the batch. ``status`` is the HTTP status of the + last attempt, or ``0`` when no response arrived (``__cause__`` holds the + transport error). A 2xx ``status`` means the request succeeded but some + events were dropped or ran out of retries. + + ``event_results`` maps each event uuid to its last verdict from a 2xx + response. Events missing from it never got a verdict, because every + attempt that reached them failed as a whole request. + + ``drops`` lists each event the server dropped on a 2xx response as a + :class:`CaptureDroppedEvent`. + """ + + def __init__( + self, + status: int | str, + message: str, + *, + endpoint: str, + retry_after: Optional[float] = None, + request_id: Optional[str] = None, + attempts: Optional[int] = None, + retry_exhausted: Optional[list[str]] = None, + drops: Optional[Sequence[tuple[str, Optional[str]]]] = None, + event_results: Optional[dict[str, CaptureEventResult]] = None, + ): + super().__init__(status, message, retry_after=retry_after) + # Capture path the batch was sent to, so one on_error handler can tell + # the analytics and AI lanes apart. + self.endpoint = endpoint + self.request_id = request_id + self.attempts = attempts + # uuids the server told us to retry but we never delivered (exhausted). + self.retry_exhausted = retry_exhausted or [] + # Plain (uuid, details) tuples are accepted, so callers can build one by hand. + self.drops = [CaptureDroppedEvent(*drop) for drop in drops or []] + self.event_results = event_results or {} + + def verdict_summary(self) -> str: + """Count the undelivered events by verdict and reason, for example + ``drop/llm_events_over_quota=2, retry/not_persisted=1``. + + Counts the events in ``drops`` and ``retry_exhausted``: events the + server dropped, and events still pending retry after the last 2xx + response. A retry verdict followed by a failed request, for example a + 503 on the last attempt, is not counted; ``event_results`` keeps it. + Empty when no event is counted. + """ + counts: dict[str, int] = {} + + def count(result: str, details: Optional[str]) -> None: + tag = f"{result}/{details}" if details else result + counts[tag] = counts.get(tag, 0) + 1 + + # A dropped duplicate shares its uuid with the kept copy, so each drop + # counts its own reason rather than the uuid's verdict. + for _, details in self.drops: + count(_RESULT_DROP, details) + for uid in self.retry_exhausted: + verdict = self.event_results.get(uid) + if verdict is not None and verdict.result: + count(verdict.result, verdict.details) + return ", ".join(f"{tag}={n}" for tag, n in sorted(counts.items())) + + +def _is_success_status(status: int) -> bool: + return 200 <= status < 300 + + +def _canonical_uuid(value: str) -> str: + """Return ``value`` in the lowercase hyphenated form capture keys results by. + + ``before_send`` can set any uuid form capture parses. A value that does not + parse is returned unchanged; capture rejects its whole batch anyway. + """ + try: + return str(UUID(value)) + except (TypeError, ValueError, AttributeError): + return value + + +def _undelivered_count(error: Exception, batch_size: int) -> int: + if not isinstance(error, CaptureError): + return batch_size + delivered = sum( + 1 + for r in error.event_results.values() + if r.result not in (_RESULT_DROP, _RESULT_RETRY) + ) + return max(0, batch_size - delivered) + + +def _capture_loss_message(error: Exception, batch_size: int, endpoint: str) -> str: + """One aggregate line for a failed batch, for callers with no ``on_error``. + + It never names individual events, includes payloads, or repeats the server's + error text: any of them may carry sensitive content, and per-event lines + scale with event volume. + """ + count = _undelivered_count(error, batch_size) + if isinstance(error, CaptureError): + endpoint = error.endpoint + if isinstance(error.status, int) and _is_success_status(error.status): + detail = f"{len(error.drops)} dropped, {len(error.retry_exhausted)} out of retries" + summary = error.verdict_summary() + if summary: + detail = f"{detail} ({summary})" + return f"{count} event(s) not persisted by {endpoint}: {detail}" + detail = type(error).__name__ + if error.__cause__ is not None: + detail = f"{detail} from {type(error.__cause__).__name__}" + status = getattr(error, "status", None) + if status is not None: + detail = f"{detail} (status={status})" + return f"{count} event(s) not persisted by {endpoint}: {detail}" + + +def _parse_retry_after(header_value: Optional[str]) -> Optional[float]: + """Parse a ``Retry-After`` header (delta-seconds or HTTP-date) to seconds.""" + if not header_value: + return None + try: + return float(header_value) + except (ValueError, TypeError): + pass + try: + delta = parsedate_to_datetime(header_value) - datetime.now(timezone.utc) + return max(0.0, delta.total_seconds()) + except (ValueError, TypeError): + return None + + +def _compress_v1( + compression: CaptureCompression, data: str +) -> tuple[str | bytes, Optional[str]]: + """Compress a v1 request body, returning ``(body, Content-Encoding token)``. + + ``GZIP`` emits a gzip stream; ``DEFLATE`` emits a *zlib-wrapped* deflate + stream (RFC 1950, leading ``0x78``) to match posthog-go / posthog-rs and the + server's zlib decoder for ``Content-Encoding: deflate`` — raw, headerless + deflate would be misrouted. ``ZSTD`` emits a standard zstd frame via the + optional zstandard package. ``NONE`` returns the string body and no token. + """ + if compression == CaptureCompression.GZIP: + buf = BytesIO() + with GzipFile(fileobj=buf, mode="w") as gz: + # `data` is produced by json.dumps(), whose default encoding is utf-8. + gz.write(data.encode("utf-8")) + return buf.getvalue(), "gzip" + if compression == CaptureCompression.DEFLATE: + return zlib.compress(data.encode("utf-8")), "deflate" + if compression == CaptureCompression.ZSTD: + # _resolve_capture_compression only yields ZSTD when zstandard is + # importable; this guard covers direct Consumer construction. + if _zstandard is None: + raise ValueError( + "capture_compression 'zstd' requires the zstandard package; " + "install posthog[zstd]" + ) + return _zstandard.ZstdCompressor().compress(data.encode("utf-8")), "zstd" + return data, None + + +def _origin(url: str) -> Optional[tuple[str, str, int]]: + # Prepare the URL as requests sends it, so a Unicode host matches its IDNA form. + prepared = PreparedRequest() + try: + prepared.prepare_url(url, None) + parsed = urlsplit(prepared.url or "") + port = parsed.port + except (RequestException, UnicodeError, ValueError): + return None + if port is None: + port = 443 if parsed.scheme.lower() == "https" else 80 + return parsed.scheme.lower(), (parsed.hostname or "").lower(), port + + +def _same_origin_redirect_url( + base_url: str, current_url: str, location: Optional[str] +) -> Optional[str]: + """Return the redirect target on ``base_url``'s origin, or ``None``.""" + if not location: + return None + target = urlsplit(urljoin(current_url, location)) + base_origin = _origin(base_url) + if base_origin is None or _origin(target.geturl()) != base_origin: + return None + return ( + urlsplit(base_url) + ._replace(path=target.path or "/", query=target.query, fragment="") + .geturl() + ) + + +def _post_v1( + api_key: str, + host: Optional[str], + batch_body: dict, + *, + attempt: int, + request_id: str, + compression: CaptureCompression = CaptureCompression.NONE, + timeout: float = 15, + sdk_info: str = USER_AGENT, + session: Optional["requests.Session"] = None, + path: str = _CAPTURE_V1_PATH, +) -> "requests.Response": + """Perform a single capture v1 ``POST`` to ``path``. + + Bearer-authed (no ``api_key`` in the body) with the required v1 headers. + ``attempt`` (1-based) and the stable ``request_id`` are echoed via + ``PostHog-Attempt``/``PostHog-Request-Id`` so the backend can correlate + retries. The body is compressed per ``compression`` (advertised via + ``Content-Encoding``). Returns the raw response; classification is left to + the caller. + + Follows only 307/308 redirects to the origin of ``host``, at most + :data:`_MAX_REDIRECTS` times, resending the same body and headers. Any other + redirect comes back as the response, which the caller treats as a terminal + failure, so a batch never goes to another origin. + """ + trimmed_host = remove_trailing_slash(normalize_host(host)) + url = trimmed_host + path + # Every event was serialized on its own with allow_nan=False before it + # joined the batch, so this never raises for an event the SDK accepted. + data = json.dumps(batch_body, cls=DatetimeSerializer, allow_nan=False) + headers = { + "Content-Type": "application/json", + "User-Agent": sdk_info, + "Authorization": f"Bearer {api_key}", + _HEADER_SDK_INFO: sdk_info, + _HEADER_ATTEMPT: str(attempt), + _HEADER_REQUEST_ID: request_id, + _HEADER_REQUEST_TIMESTAMP: _rfc3339_timestamp(datetime.now(timezone.utc)), + } + body, encoding = _compress_v1(compression, data) + if encoding is not None: + headers["Content-Encoding"] = encoding + + log.debug("capture v1 POST %s attempt=%s request_id=%s", url, attempt, request_id) + http = session or _get_capture_session() + for _ in range(_MAX_REDIRECTS + 1): + res = http.post( + url, data=body, headers=headers, timeout=timeout, allow_redirects=False + ) + if res.status_code not in _REDIRECT_STATUSES: + return res + target = _same_origin_redirect_url( + trimmed_host, url, res.headers.get("Location") + ) + if target is None: + log.debug( + "capture v1 did not follow a %s redirect to another origin", + res.status_code, + ) + return res + url = target + log.debug("capture v1 stopped after %d redirects", _MAX_REDIRECTS) + return res + + +def _parse_v1_response(res: "requests.Response") -> _V1ParsedResponse: + """Read and classify a v1 response without raising.""" + status = res.status_code + retry_after = _parse_retry_after(res.headers.get("Retry-After")) + + if _is_success_status(status): + try: + payload = res.json() + results: dict[str, CaptureEventResult] = {} + duplicates_dropped: dict[str, int] = {} + for uid, r in payload["results"].items(): + r = r or {} + results[uid] = CaptureEventResult( + result=r.get("result"), details=r.get("details") + ) + count = r.get("duplicates_dropped") + if isinstance(count, int) and not isinstance(count, bool) and count > 0: + duplicates_dropped[uid] = count + return _V1ParsedResponse( + status, + True, + retry_after, + results=results, + duplicates_dropped=duplicates_dropped, + ) + except (ValueError, KeyError, AttributeError, TypeError): + # 2xx with a body we can't read as a results map: terminal, so we + # don't loop forever re-sending against a broken success. + return _V1ParsedResponse(status, True, retry_after, malformed=True) + + message = "" + try: + payload = res.json() + if isinstance(payload, dict): + message = ( + payload.get("error_description") + or payload.get("error") + or payload.get("detail") + or "" + ) + except (ValueError, AttributeError): + pass + if not message: + message = res.text or f"capture v1 request failed with status {status}" + return _V1ParsedResponse(status, False, retry_after, error_message=message) + + +def _draw_jitter() -> float: + return 1 - _BACKOFF_JITTER + random.random() * _BACKOFF_JITTER * 2 + + +def _backoff(attempt_index: int, retry_after: Optional[float]) -> None: + """Sleep before the next attempt. + + Exponential backoff, spread by :data:`_BACKOFF_JITTER` and then capped at + :data:`_MAX_BACKOFF_SECONDS`, is the base. When the server sent a + ``Retry-After`` it acts as a *minimum*, not a replacement: + the client waits the longer of the configured backoff and ``Retry-After``, so + a small ``Retry-After`` never retries earlier than the normal schedule + (matching posthog-go / posthog-rs). ``Retry-After`` is itself clamped to + :data:`_MAX_BACKOFF_SECONDS`, so both sides share one ceiling and a + hostile/buggy header can't park the consumer thread. + """ + configured = min( + _BACKOFF_BASE_SECONDS * 2**attempt_index * _draw_jitter(), _MAX_BACKOFF_SECONDS + ) + clamped_retry_after = ( + min(retry_after, _MAX_BACKOFF_SECONDS) if retry_after and retry_after > 0 else 0 + ) + time.sleep(max(configured, clamped_retry_after)) + + +def _log_result_summary( + request_id: str, attempt: int, results: dict[str, CaptureEventResult] +) -> None: + tally = {_RESULT_OK: 0, _RESULT_WARNING: 0, _RESULT_DROP: 0, _RESULT_RETRY: 0} + other = 0 + for r in results.values(): + if r.result in tally: + tally[r.result] += 1 + else: + other += 1 + log.debug( + "capture v1 response request_id=%s attempt=%s events=%d ok=%d warning=%d drop=%d retry=%d other=%d", + request_id, + attempt, + len(results), + tally[_RESULT_OK], + tally[_RESULT_WARNING], + tally[_RESULT_DROP], + tally[_RESULT_RETRY], + other, + ) + + +def _send_v1_batch( + api_key: str, + host: Optional[str], + batch: list[dict], + *, + compression: CaptureCompression = CaptureCompression.NONE, + timeout: float = 15, + max_retries: int = 3, + historical_migration: bool = False, + sdk_info: str = USER_AGENT, + session: Optional["requests.Session"] = None, + path: str = _CAPTURE_V1_PATH, +) -> None: + """Deliver ``batch`` to the v1 endpoint at ``path`` with partial retry. + + Loops up to ``max_retries + 1`` attempts. After each 2xx it resends only + the events the server tagged ``retry``. ``ok``/``warning`` events, events + with an unrecognized verdict, and events absent from ``results`` succeed + (matching posthog-go and posthog-rs). Results are matched by canonical + uuid, because capture keys them that way whatever form was sent. + + A server-chosen ``drop`` is a terminal per-event rejection. Drops are + accumulated across attempts and surfaced via :class:`CaptureError` even + when the request itself was a 2xx (a success status is not full delivery) + and even when a later attempt clears the outstanding retries — matching + posthog-go (per-event failure callback) and posthog-rs (``on_error`` on a + 2xx with undelivered verdicts). When a result carries + ``duplicates_dropped: n``, the first event with that uuid takes the verdict + and the next ``n`` copies become drops with reason ``duplicate_event_uuid``, + never resent. Raises :class:`CaptureError` on any drop, + batch-level terminal failure, retry exhaustion, or transport failure + (``status`` 0, chained to the transport error), carrying the endpoint, the + accumulated ``drops``, any exhausted uuids, and every verdict seen so far, + so the caller's ``on_error`` gets the full picture. + ``request_id`` and the batch ``created_at`` are stable across attempts; + ``PostHog-Attempt`` increments. Negative ``max_retries`` values are treated + as zero, so delivery is always attempted at least once. + """ + max_retries = max(0, max_retries) + request_id = str(_uuid7()) + # Hoisted once so the batch envelope is byte-identical across retry attempts + # (only the events list shrinks and the attempt header increments). + created_at = _rfc3339_timestamp(datetime.now(timezone.utc)) + pending_events = [_to_v1_event(m) for m in batch] + pending_uuids = [_canonical_uuid(e["uuid"]) for e in pending_events] + # (uuid, details) for every event the server dropped, across all attempts. + # Accumulated (not per-attempt) so a drop seen early is not lost when a + # later attempt succeeds or clears the outstanding retries. + all_drops: list[CaptureDroppedEvent] = [] + # Latest 2xx verdict per uuid, across all attempts. + event_results: dict[str, CaptureEventResult] = {} + + def capture_error( + status: int, + message: str, + *, + attempts: int, + retry_after: Optional[float] = None, + retry_exhausted: Optional[list[str]] = None, + ) -> CaptureError: + return CaptureError( + status, + message, + endpoint=path, + retry_after=retry_after, + request_id=request_id, + attempts=attempts, + retry_exhausted=retry_exhausted, + drops=all_drops, + event_results=event_results, + ) + + for attempt_index in range(max_retries + 1): + attempt = attempt_index + 1 + last_attempt = attempt_index == max_retries + body = _build_v1_batch_body( + pending_events, historical_migration, created_at=created_at + ) + + try: + res = _post_v1( + api_key, + host, + body, + attempt=attempt, + request_id=request_id, + compression=compression, + timeout=timeout, + sdk_info=sdk_info, + session=session, + path=path, + ) + except Exception as e: + # Transport-level failure (connection/timeout): retryable. + if last_attempt: + raise capture_error( + 0, f"{type(e).__name__}: {e}", attempts=attempt + ) from e + _backoff(attempt_index, None) + continue + + parsed = _parse_v1_response(res) + + if parsed.is_success: + if parsed.malformed: + raise capture_error( + parsed.status_code, + "capture v1 returned a success status with an unparseable body", + attempts=attempt, + ) + results = parsed.results or {} + _log_result_summary(request_id, attempt, results) + + retry_events: list[dict] = [] + retry_uuids: list[str] = [] + duplicates_left = dict(parsed.duplicates_dropped) + seen_duplicated: set[str] = set() + for event, uid in zip(pending_events, pending_uuids): + directive = results.get(uid) + if directive is None: + # Absent from the map: treated as accepted (matches + # posthog-go and posthog-rs). Capture answers every event + # of a 2xx, so this only happens if it breaks that contract. + continue + if uid in duplicates_left: + if uid in seen_duplicated and duplicates_left[uid] > 0: + duplicates_left[uid] -= 1 + all_drops.append( + CaptureDroppedEvent(uid, _DUPLICATE_EVENT_UUID) + ) + continue + seen_duplicated.add(uid) + event_results[uid] = directive + if directive.result == _RESULT_RETRY: + retry_events.append(event) + retry_uuids.append(uid) + elif directive.result == _RESULT_DROP: + # Terminal per-event rejection; keep it so it is surfaced + # even when the rest of the batch succeeds (see below). + all_drops.append(CaptureDroppedEvent(uid, directive.details)) + # ok / warning / unrecognized -> terminal success. + + if not retry_uuids: + # Nothing left to resend. If the server dropped any events, + # surface them via on_error even though the request was a 2xx — + # a success status does not mean every event was delivered. + if all_drops: + raise capture_error( + parsed.status_code, + f"{len(all_drops)} event(s) dropped by the server", + attempts=attempt, + ) + return + if last_attempt: + raise capture_error( + parsed.status_code, + f"{len(retry_uuids)} event(s) still pending retry after {attempt} attempt(s)", + attempts=attempt, + retry_exhausted=retry_uuids, + ) + pending_events, pending_uuids = retry_events, retry_uuids + _backoff(attempt_index, parsed.retry_after) + continue + + # Non-2xx. Retryable transient statuses back off; everything else + # (400/401/402/413/415/...) is terminal. Any drops collected from a + # prior 2xx attempt ride along so on_error still sees them. + v1_error = capture_error( + parsed.status_code, + parsed.error_message, + retry_after=parsed.retry_after, + attempts=attempt, + ) + if parsed.status_code in _RETRYABLE_STATUSES and not last_attempt: + _backoff(attempt_index, parsed.retry_after) + continue + raise v1_error diff --git a/posthog/capture_v1.py b/posthog/capture_v1.py deleted file mode 100644 index fb8afa7aa..000000000 --- a/posthog/capture_v1.py +++ /dev/null @@ -1,667 +0,0 @@ -"""Serialization and transport for the Capture V1 wire protocol. - -This module owns everything specific to ``POST /i/v1/analytics/events``: the -*transform* layer (legacy-shaped queued message -> v1 wire event + batch -envelope) and the *transport* layer (a single HTTP attempt, response parsing, -and the partial-retry send loop). - -The v1 contract (see ``rust/capture/src/v1/analytics/types.rs``) differs from -the legacy ``/batch/`` shape in a few load-bearing ways that this module -encodes: - -- A typed ``options`` object carries a handful of sentinel properties, renamed - and strictly typed. Wrong JSON types fail deserialization of the *whole - batch*, so values are coerced to native types or omitted entirely. -- ``$set``/``$set_once`` have no top-level form in v1; the server reads them - from ``properties``. The legacy ``set()``/``set_once()`` builders emit them at - the top level, so they are relocated into ``properties`` here. -- ``$lib``/``$lib_version`` are injected server-side from the required - ``PostHog-Sdk-Info`` header and are stripped from v1 properties. - -The response is per-event: a 200 carries a ``results`` map keyed by event uuid, -each tagged ``ok``/``warning`` (terminal-success), ``drop`` (terminal-failure), -or ``retry``. :func:`_send_v1_batch` resends only the ``retry`` events on the next -attempt, holding the ``PostHog-Request-Id`` and batch ``created_at`` stable -across attempts while incrementing ``PostHog-Attempt``. ``ok``/``warning``/absent -events succeed; ``drop`` and retry-exhaustion are carried on the -:class:`CaptureV1Error` raised on batch-level/terminal failure, so the consumer's -existing ``on_error(exc, batch)`` path surfaces them unchanged (no per-event -logging of its own). - -Request bodies are optionally compressed per :class:`~posthog.capture_compression.CaptureCompression` -(``gzip`` or zlib-wrapped ``deflate``), advertised via ``Content-Encoding``. -""" - -import json -import logging -import time -import zlib -from collections.abc import Callable -from dataclasses import dataclass -from datetime import datetime, timezone -from email.utils import parsedate_to_datetime -from gzip import GzipFile -from io import BytesIO -from typing import TYPE_CHECKING, Any, Optional -from uuid import uuid4 - -from posthog.capture_compression import CaptureCompression, _zstandard -from posthog.request import ( - DatetimeSerializer, - USER_AGENT, - APIError, - _get_session, - normalize_host, -) -from posthog.utils import _normalize_timestamp, remove_trailing_slash - -if TYPE_CHECKING: - import requests - -log = logging.getLogger("posthog") - -# Only the error type is public API: it reaches user code through `on_error` -# callbacks, so callers may want to catch/inspect it. Everything else is -# submitter plumbing. -__all__ = ["CaptureV1Error"] - -_CAPTURE_V1_PATH = "/i/v1/analytics/events" - -# Required request/response headers for the v1 endpoint. Defined here as the -# single source of truth; the transport layer builds requests from them. -_HEADER_SDK_INFO = "PostHog-Sdk-Info" -_HEADER_ATTEMPT = "PostHog-Attempt" -_HEADER_REQUEST_ID = "PostHog-Request-Id" -_HEADER_REQUEST_TIMESTAMP = "PostHog-Request-Timestamp" - -# Per-event result codes the backend emits (rust EventResult). `ok`/`warning` -# are terminal-success; `drop` terminal-failure; `retry` is safe to resend. -_RESULT_OK = "ok" -_RESULT_WARNING = "warning" -_RESULT_DROP = "drop" -_RESULT_RETRY = "retry" - -# HTTP status classification. 404 and 429 can come from a proxy in front of capture. -_RETRYABLE_STATUSES = frozenset({404, 408, 429, 500, 502, 503, 504}) -_TERMINAL_STATUSES = frozenset({400, 401, 402, 413, 415}) - -# Single ceiling (seconds) for the retry backoff: caps the exponential schedule -# and clamps a server ``Retry-After`` to the same value. Keeps the max retry -# wait bounded (a hostile/buggy header can't park the consumer thread) and -# unifies the default with posthog-go/posthog-rs (all 30s). -_MAX_BACKOFF_SECONDS = 30 - -# Sentinel properties lifted to top-level string fields on the event. -_TOPLEVEL_SENTINELS: tuple[tuple[str, str], ...] = ( - ("$session_id", "session_id"), - ("$window_id", "window_id"), -) - -# Top-level legacy keys relocated into properties (v1 has no top-level form). -_RELOCATE_TO_PROPERTIES = ("$set", "$set_once") - -# Properties dropped from v1 events (server injects them from PostHog-Sdk-Info). -_STRIP_FROM_PROPERTIES = ("$lib", "$lib_version") - - -def _coerce_bool(value: Any) -> Optional[bool]: - """Coerce a sentinel value to ``bool`` using the backend's truthiness rules. - - Native bool passes through; ``"true"``/``"1"`` and ``"false"``/``"0"`` - (case-insensitive, trimmed) map to the obvious bool; any other numeric value - is nonzero-truthy. Anything else returns ``None`` so the option is omitted - rather than sent with a type the strict v1 schema would reject. - """ - if isinstance(value, bool): - return value - if isinstance(value, str): - normalized = value.strip().lower() - if normalized in ("true", "1"): - return True - if normalized in ("false", "0"): - return False - return None - if isinstance(value, (int, float)): - return value != 0 - return None - - -def _coerce_str(value: Any) -> Optional[str]: - """Accept only ``str`` (the backend's ``product_tour_id`` is ``Option``).""" - return value if isinstance(value, str) else None - - -# Sentinel properties lifted into the typed `options` object: legacy property -# key, the backend's field name, and the coercer enforcing its strict type -# (wrong JSON types fail deserialization of the whole batch, so a value that -# won't coerce is omitted). The coercer is stored directly to keep the dispatch -# type-checked rather than keyed by a stringly-typed name. -_OPTION_SENTINELS: tuple[tuple[str, str, Callable[[Any], Any]], ...] = ( - ("$cookieless_mode", "cookieless_mode", _coerce_bool), - ("$ignore_sent_at", "disable_skew_correction", _coerce_bool), - ("$product_tour_id", "product_tour_id", _coerce_str), - ("$process_person_profile", "process_person_profile", _coerce_bool), -) - - -def _v1_timestamp(timestamp: Any) -> str: - """Return a UTC RFC3339 timestamp string. - - Messages off the queue already carry a UTC ISO-8601 string (``_enqueue`` - normalizes canonical datetimes), so that is passed through. A ``datetime`` - is normalized to UTC and serialized; a missing value defaults to now in UTC. - The v1 server parses strictly with ``DateTime::parse_from_rfc3339`` and - rejects naive timestamps. - """ - if timestamp is None: - return datetime.now(timezone.utc).isoformat() - return _normalize_timestamp(timestamp) - - -def _to_v1_event(msg: dict) -> dict: - """Transform a legacy-shaped queued message into a v1 wire event. - - Pure: the input ``msg`` is not mutated (a fresh ``properties`` dict is - built), so it remains safe to keep the original for retries or callbacks. - """ - properties = dict(msg.get("properties") or {}) - - _relocate_v1_properties(msg, properties) - - for key in _STRIP_FROM_PROPERTIES: - properties.pop(key, None) - - options: dict[str, Any] = {} - for prop_key, wire_key, coercer in _OPTION_SENTINELS: - if prop_key not in properties: - continue - # Always removed from properties — these sentinels must never reach v1 - # backend properties — but only emitted as an option when coercible. - coerced = coercer(properties.pop(prop_key)) - if coerced is not None: - options[wire_key] = coerced - - top_level: dict[str, str] = {} - for prop_key, field_name in _TOPLEVEL_SENTINELS: - if prop_key not in properties: - continue - coerced_str = _coerce_str(properties.pop(prop_key)) - if coerced_str is not None: - top_level[field_name] = coerced_str - - event = { - "event": msg["event"], - "uuid": msg["uuid"], - "distinct_id": msg["distinct_id"], - "timestamp": _v1_timestamp(msg.get("timestamp")), - # Always a dict so it serializes as "{}" rather than null when empty. - "options": options, - "properties": properties, - } - event.update(top_level) - return event - - -def _build_v1_batch_body( - events: list[dict], - historical_migration: bool = False, - created_at: Optional[str] = None, -) -> dict: - """Assemble the v1 batch envelope. - - Carries no ``api_key`` (Bearer auth) and no ``sent_at``. - ``historical_migration`` is omitted when False (the server defaults it). - ``created_at`` defaults to now in UTC; :func:`_send_v1_batch` passes a value - hoisted once so it stays stable across retry attempts. - """ - body: dict[str, Any] = { - "created_at": created_at or datetime.now(timezone.utc).isoformat(), - "batch": events, - } - if historical_migration: - body["historical_migration"] = True - return body - - -@dataclass -class _V1EventResult: - """A single event's directive from a 2xx ``results`` map.""" - - result: Optional[str] - details: Optional[str] = None - - -@dataclass -class _V1ParsedResponse: - """Classified outcome of one v1 HTTP attempt. - - ``is_success`` is the 2xx classification. On success ``results`` holds the - per-uuid directives (``None``/``malformed=True`` when the body could not be - parsed — treated as terminal so a bad success never loops forever). On a - non-2xx, ``error_message`` is the best-effort human-readable detail. - """ - - status_code: int - is_success: bool - retry_after: Optional[float] = None - results: Optional[dict[str, _V1EventResult]] = None - malformed: bool = False - error_message: str = "" - - -class CaptureV1Error(APIError): - """Batch-level failure of a capture-v1 send. - - Subclasses :class:`APIError` so the consumer's existing ``on_error`` handling - (which already inspects ``status``/``retry_after``) keeps working; the extra - fields carry v1 specifics for richer logging/callbacks. - """ - - def __init__( - self, - status: int | str, - message: str, - *, - retry_after: Optional[float] = None, - request_id: Optional[str] = None, - attempts: Optional[int] = None, - retry_exhausted: Optional[list[str]] = None, - drops: Optional[list[tuple[str, Optional[str]]]] = None, - ): - super().__init__(status, message, retry_after=retry_after) - self.request_id = request_id - self.attempts = attempts - # uuids the server told us to retry but we never delivered (exhausted). - self.retry_exhausted = retry_exhausted or [] - # (uuid, details) pairs the server told us to drop on a 2xx response. - self.drops = drops or [] - - -def _is_success_status(status: int) -> bool: - return 200 <= status < 300 - - -def _parse_retry_after(header_value: Optional[str]) -> Optional[float]: - """Parse a ``Retry-After`` header (delta-seconds or HTTP-date) to seconds.""" - if not header_value: - return None - try: - return float(header_value) - except (ValueError, TypeError): - pass - try: - delta = parsedate_to_datetime(header_value) - datetime.now(timezone.utc) - return max(0.0, delta.total_seconds()) - except (ValueError, TypeError): - return None - - -def _compress_v1( - compression: CaptureCompression, data: str -) -> tuple[str | bytes, Optional[str]]: - """Compress a v1 request body, returning ``(body, Content-Encoding token)``. - - ``GZIP`` emits a gzip stream; ``DEFLATE`` emits a *zlib-wrapped* deflate - stream (RFC 1950, leading ``0x78``) to match posthog-go / posthog-rs and the - server's zlib decoder for ``Content-Encoding: deflate`` — raw, headerless - deflate would be misrouted. ``ZSTD`` emits a standard zstd frame via the - optional zstandard package. ``NONE`` returns the string body and no token. - """ - if compression == CaptureCompression.GZIP: - buf = BytesIO() - with GzipFile(fileobj=buf, mode="w") as gz: - # `data` is produced by json.dumps(), whose default encoding is utf-8. - gz.write(data.encode("utf-8")) - return buf.getvalue(), "gzip" - if compression == CaptureCompression.DEFLATE: - return zlib.compress(data.encode("utf-8")), "deflate" - if compression == CaptureCompression.ZSTD: - # _resolve_capture_compression only yields ZSTD when zstandard is - # importable; this guard covers direct Consumer construction. - if _zstandard is None: - raise ValueError( - "capture_compression 'zstd' requires the zstandard package; " - "install posthog[zstd]" - ) - return _zstandard.ZstdCompressor().compress(data.encode("utf-8")), "zstd" - return data, None - - -def _post_v1( - api_key: str, - host: Optional[str], - batch_body: dict, - *, - attempt: int, - request_id: str, - compression: CaptureCompression = CaptureCompression.NONE, - timeout: float = 15, - sdk_info: str = USER_AGENT, - session: Optional["requests.Session"] = None, -) -> "requests.Response": - """Perform a single ``POST /i/v1/analytics/events`` attempt. - - Bearer-authed (no ``api_key`` in the body) with the required v1 headers. - ``attempt`` (1-based) and the stable ``request_id`` are echoed via - ``PostHog-Attempt``/``PostHog-Request-Id`` so the backend can correlate - retries. The body is compressed per ``compression`` (advertised via - ``Content-Encoding``). Returns the raw response; classification is left to - the caller. - """ - trimmed_host = remove_trailing_slash(normalize_host(host)) - url = trimmed_host + _CAPTURE_V1_PATH - data = json.dumps(batch_body, cls=DatetimeSerializer) - headers = { - "Content-Type": "application/json", - "User-Agent": sdk_info, - "Authorization": f"Bearer {api_key}", - _HEADER_SDK_INFO: sdk_info, - _HEADER_ATTEMPT: str(attempt), - _HEADER_REQUEST_ID: request_id, - _HEADER_REQUEST_TIMESTAMP: datetime.now(timezone.utc).isoformat(), - } - body, encoding = _compress_v1(compression, data) - if encoding is not None: - headers["Content-Encoding"] = encoding - - log.debug("capture v1 POST %s attempt=%s request_id=%s", url, attempt, request_id) - return (session or _get_session()).post( - url, data=body, headers=headers, timeout=timeout - ) - - -def _parse_v1_response(res: "requests.Response") -> _V1ParsedResponse: - """Read and classify a v1 response without raising.""" - status = res.status_code - retry_after = _parse_retry_after(res.headers.get("Retry-After")) - - if _is_success_status(status): - try: - payload = res.json() - raw_results = payload["results"] - results = { - uid: _V1EventResult( - result=(r or {}).get("result"), - details=(r or {}).get("details"), - ) - for uid, r in raw_results.items() - } - return _V1ParsedResponse(status, True, retry_after, results=results) - except (ValueError, KeyError, AttributeError, TypeError): - # 2xx with a body we can't read as a results map: terminal, so we - # don't loop forever re-sending against a broken success. - return _V1ParsedResponse(status, True, retry_after, malformed=True) - - return _V1ParsedResponse( - status, False, retry_after, error_message=_v1_error_message(res, status) - ) - - -def _backoff(attempt_index: int, retry_after: Optional[float]) -> None: - """Sleep before the next attempt. - - Exponential backoff capped at :data:`_MAX_BACKOFF_SECONDS` is the base. When - the server sent a ``Retry-After`` it acts as a *minimum*, not a replacement: - the client waits the longer of the configured backoff and ``Retry-After``, so - a small ``Retry-After`` never retries earlier than the normal schedule - (matching posthog-go / posthog-rs). ``Retry-After`` is itself clamped to - :data:`_MAX_BACKOFF_SECONDS`, so both sides share one ceiling and a - hostile/buggy header can't park the consumer thread. - """ - configured = min(2**attempt_index, _MAX_BACKOFF_SECONDS) - clamped_retry_after = ( - min(retry_after, _MAX_BACKOFF_SECONDS) if retry_after and retry_after > 0 else 0 - ) - time.sleep(max(configured, clamped_retry_after)) - - -def _log_result_summary( - request_id: str, attempt: int, results: dict[str, _V1EventResult] -) -> None: - tally = {_RESULT_OK: 0, _RESULT_WARNING: 0, _RESULT_DROP: 0, _RESULT_RETRY: 0} - other = 0 - for r in results.values(): - if r.result in tally: - tally[r.result] += 1 - else: - other += 1 - log.debug( - "capture v1 response request_id=%s attempt=%s events=%d ok=%d warning=%d drop=%d retry=%d other=%d", - request_id, - attempt, - len(results), - tally[_RESULT_OK], - tally[_RESULT_WARNING], - tally[_RESULT_DROP], - tally[_RESULT_RETRY], - other, - ) - - -def _send_v1_batch( - api_key: str, - host: Optional[str], - batch: list[dict], - *, - compression: CaptureCompression = CaptureCompression.NONE, - timeout: float = 15, - max_retries: int = 3, - historical_migration: bool = False, - sdk_info: str = USER_AGENT, - session: Optional["requests.Session"] = None, -) -> None: - """Deliver ``batch`` to the v1 endpoint with partial retry. - - The v1 sibling of ``Consumer._send``: it loops up to ``max_retries + 1`` - attempts, but unlike v0 it shrinks the batch to only the events the server - tagged ``retry`` after each 2xx. ``ok``/``warning``/absent events succeed. - - A server-chosen ``drop`` is a terminal per-event rejection. Drops are - accumulated across attempts and surfaced via :class:`CaptureV1Error` even - when the request itself was a 2xx (a success status is not full delivery) - and even when a later attempt clears the outstanding retries — matching - posthog-go (per-event failure callback) and posthog-rs (``on_error`` on a - 2xx with undelivered verdicts). Raises :class:`CaptureV1Error` on any drop, - batch-level terminal failure, or retry exhaustion — carrying the accumulated - ``drops`` and any exhausted uuids — so the caller's ``on_error`` fires - unchanged. A transport failure re-raises the underlying exception (drops - collected on an earlier attempt are still tallied in the DEBUG summary). - ``request_id`` and the batch ``created_at`` are stable across attempts; - ``PostHog-Attempt`` increments. Negative ``max_retries`` values are treated - as zero, so delivery is always attempted at least once. - """ - max_retries = max(0, max_retries) - request_id = str(uuid4()) - # Hoisted once so the batch envelope is byte-identical across retry attempts - # (only the events list shrinks and the attempt header increments). - created_at = datetime.now(timezone.utc).isoformat() - pending_events = [_to_v1_event(m) for m in batch] - pending_uuids = [e["uuid"] for e in pending_events] - last_exc: Optional[Exception] = None - # (uuid, details) for every event the server dropped, across all attempts. - # Accumulated (not per-attempt) so a drop seen early is not lost when a - # later attempt succeeds or clears the outstanding retries. - all_drops: list[tuple[str, Optional[str]]] = [] - - for attempt_index in range(max_retries + 1): - attempt = attempt_index + 1 - last_attempt = attempt_index == max_retries - body = _build_v1_batch_body( - pending_events, historical_migration, created_at=created_at - ) - - try: - res = _post_v1( - api_key, - host, - body, - attempt=attempt, - request_id=request_id, - compression=compression, - timeout=timeout, - sdk_info=sdk_info, - session=session, - ) - except Exception as e: - # Transport-level failure (connection/timeout): retry like v0 does. - last_exc = e - if last_attempt: - raise - _backoff(attempt_index, None) - continue - - parsed = _parse_v1_response(res) - - if parsed.is_success: - pending_events, pending_uuids = _apply_v1_results( - parsed, - pending_events, - pending_uuids, - all_drops, - request_id, - attempt, - last_attempt, - ) - if not pending_uuids: - return - _backoff(attempt_index, parsed.retry_after) - continue - - # Non-2xx. Retryable transient statuses back off; everything else - # (400/401/402/413/415/...) is terminal. Any drops collected from a - # prior 2xx attempt ride along so on_error still sees them. - last_exc = _v1_batch_failure( - parsed, request_id, attempt, all_drops, last_attempt - ) - _backoff(attempt_index, parsed.retry_after) - - # Unreachable in practice (every branch returns or continues). - if last_exc: - raise last_exc - - -def _relocate_v1_properties(msg: dict, properties: dict) -> None: - # Relocate top-level $set/$set_once into properties; v1 has no top-level - # form. On the unusual collision where properties already carries the key, - # the properties value wins. - for key in _RELOCATE_TO_PROPERTIES: - top_val = msg.get(key) - if top_val is None: - continue - existing = properties.get(key) - if isinstance(top_val, dict) and isinstance(existing, dict): - properties[key] = {**top_val, **existing} - elif key not in properties: - properties[key] = top_val - - -def _v1_error_message(res: "requests.Response", status: int) -> str: - message = "" - try: - payload = res.json() - if isinstance(payload, dict): - message = ( - payload.get("error_description") - or payload.get("error") - or payload.get("detail") - or "" - ) - except (ValueError, AttributeError): - pass - if not message: - message = res.text or f"capture v1 request failed with status {status}" - return message - - -def _apply_v1_results( - parsed: _V1ParsedResponse, - pending_events: list[dict], - pending_uuids: list[str], - all_drops: list[tuple[str, Optional[str]]], - request_id: str, - attempt: int, - last_attempt: bool, -) -> tuple[list[dict], list[str]]: - if parsed.malformed: - raise CaptureV1Error( - parsed.status_code, - "capture v1 returned a success status with an unparseable body", - request_id=request_id, - attempts=attempt, - drops=all_drops, - ) - results = parsed.results or {} - _log_result_summary(request_id, attempt, results) - - retry_events, retry_uuids = _partition_v1_results( - pending_events, pending_uuids, results, all_drops - ) - - if not retry_uuids: - # Nothing left to resend. If the server dropped any events, - # surface them via on_error even though the request was a 2xx — - # a success status does not mean every event was delivered. - if all_drops: - raise CaptureV1Error( - parsed.status_code, - f"{len(all_drops)} event(s) dropped by the server", - request_id=request_id, - attempts=attempt, - drops=all_drops, - ) - return [], [] - if last_attempt: - raise CaptureV1Error( - parsed.status_code, - f"{len(retry_uuids)} event(s) still pending retry after {attempt} attempt(s)", - request_id=request_id, - attempts=attempt, - retry_exhausted=retry_uuids, - drops=all_drops, - ) - return retry_events, retry_uuids - - -def _partition_v1_results( - pending_events: list[dict], - pending_uuids: list[str], - results: dict[str, _V1EventResult], - all_drops: list[tuple[str, Optional[str]]], -) -> tuple[list[dict], list[str]]: - retry_events: list[dict] = [] - retry_uuids: list[str] = [] - for event, uid in zip(pending_events, pending_uuids): - directive = results.get(uid) - if directive is None: - # Absent from the map: treated as accepted (matches posthog-rs). - continue - if directive.result == _RESULT_RETRY: - retry_events.append(event) - retry_uuids.append(uid) - elif directive.result == _RESULT_DROP: - # Terminal per-event rejection; keep it so it is surfaced - # even when the rest of the batch succeeds (see below). - all_drops.append((uid, directive.details)) - # ok / warning / unrecognized -> terminal success. - - return retry_events, retry_uuids - - -def _v1_batch_failure( - parsed: _V1ParsedResponse, - request_id: str, - attempt: int, - all_drops: list[tuple[str, Optional[str]]], - last_attempt: bool, -) -> CaptureV1Error: - error = CaptureV1Error( - parsed.status_code, - parsed.error_message, - retry_after=parsed.retry_after, - request_id=request_id, - attempts=attempt, - drops=all_drops, - ) - if parsed.status_code not in _RETRYABLE_STATUSES or last_attempt: - raise error - return error diff --git a/posthog/client.py b/posthog/client.py index 84251f16a..d71aa13d7 100644 --- a/posthog/client.py +++ b/posthog/client.py @@ -2,7 +2,9 @@ import hashlib as _hashlib import inspect import json +from contextlib import contextmanager import logging +import math import os import re import sys @@ -11,7 +13,6 @@ import warnings import weakref from contextvars import ContextVar -from dataclasses import dataclass as _dataclass from datetime import datetime, timedelta, timezone from typing import ( Any, @@ -55,10 +56,22 @@ from posthog.tracing._span import inert_span as _inert_span from posthog.capture_compression import ( CaptureCompression, + _resolve_capture_ai_compression, _resolve_capture_compression, ) -from posthog.capture_mode import CaptureMode, _resolve_capture_mode -from posthog.capture_v1 import _send_v1_batch +from posthog.capture_event import ( + _build_event_defaults, + _event_options, + _fill_event_defaults, + _merge_groups, + _resolve_event_uuid, +) +from posthog.capture_send import ( + _CAPTURE_AI_V1_PATH, + _CAPTURE_V1_PATH, + _capture_loss_message, + _send_v1_batch, +) from posthog.consumer import AI_MAX_MSG_SIZE, MAX_MSG_SIZE, Consumer, _DrainSignal from posthog.contexts import ( _get_current_context, @@ -71,11 +84,13 @@ get_context_device_id, get_context_distinct_id, get_context_session_id, + get_context_options as _context_get_context_options, get_tags as _context_get_tags, identify_context as _context_identify_context, _scoped as _context_scoped, new_context, set_context_device_id as _context_set_context_device_id, + set_context_option as _context_set_context_option, set_context_session as _context_set_context_session, tag as _context_tag, ) @@ -90,10 +105,11 @@ exc_info_from_error, exception_is_already_captured, exceptions_from_error_tuple, + _exception_level, _get_current_otel_span_properties, handle_in_app, mark_exception_as_captured, - _normalize_exception_level, + _without_reserved_exception_properties, try_attach_code_variables_to_frames, ) from posthog.feature_flag_evaluations import ( @@ -117,16 +133,11 @@ from posthog.poller import Poller from posthog.release_id import _resolve_release_id from posthog.request import ( - AI_EVENTS_ENDPOINT, - EVENTS_ENDPOINT, - USER_AGENT as _USER_AGENT, APIError, + DatetimeSerializer as _DatetimeSerializer, QuotaLimitError, RequestsConnectionError, RequestsTimeout, - _get as _get_with_identity, - _remote_config as _remote_config_with_identity, - batch_post, determine_server_host, flags, get, @@ -154,11 +165,18 @@ to_values, ) from posthog.utils import ( + _uuid7, FlagCache, RedisFlagCache, SizeLimitedDict, clean, _normalize_timestamp, + _rfc3339_timestamp, + _is_personal_api_key, + _drop_invalid_distinct_id, + _drop_invalid_event_name, + _log_before_send_bad_return, + _log_before_send_error, guess_timezone as guess_timezone, system_context, ) @@ -176,35 +194,12 @@ # overrun it by up to the client's request timeout. _TRACES_SHUTDOWN_FLUSH_SECONDS = 30.0 _atexit_deadline: Optional[float] = None +# Marks a thread that is running a sync-mode `on_error`, so a capture that fails +# inside the callback logs instead of re-entering it. +_on_error_state = threading.local() _atexit_deadline_lock = threading.Lock() -@_dataclass -class _FlagReadResult: - """Per-read result and attribution, including metadata retained on remote failure.""" - - result: Optional[FeatureFlagResult] = None - details: Optional[FeatureFlag] = None - request_id: Optional[str] = None - evaluated_at: Optional[int] = None - error: Optional[str] = None - minimal_flag_called_events: bool = False - # Only a read whose value came from details may attribute a v2 experiment split. - value_from_details: bool = False - - -@_dataclass -class _FlagEvaluationResult: - """Mutable only during one evaluation pass, then handed to its snapshot.""" - - records: Dict[str, _EvaluatedFlagRecord] - request_id: Optional[str] = None - evaluated_at: Optional[int] = None - errors_while_computing: bool = False - quota_limited: bool = False - minimal_flag_called_events: bool = False - - class _LocalEvaluationSnapshot(FlagDefinitionCacheData): flags_by_key: Dict[str, Any] flag_definition_version: int @@ -283,37 +278,59 @@ def _get_atexit_deadline() -> float: return _atexit_deadline +def _positive_config_value( + name: str, value, *, integer: bool = False, maximum: Optional[int] = None +): + """Return ``value`` if it is finite, positive and no larger than ``maximum``. + + Bad lane config is a programming error, so it raises instead of falling + back to a default. + """ + allowed = (int,) if integer else (int, float) + if ( + isinstance(value, bool) + or not isinstance(value, allowed) + or not math.isfinite(value) + or value <= 0 + ): + kind = "integer" if integer else "number" + raise ValueError(f"{name} must be a positive {kind}, got {value!r}") + if maximum is not None and value > maximum: + raise ValueError(f"{name} must be at most {maximum}, got {value!r}") + return value + + +def _explicit_distinct_id(passed) -> Optional[str]: + """The caller's distinct id, or None when it is missing, empty or whitespace.""" + stringified = stringify_id(passed) + if stringified and stringified.strip(): + return stringified + return None + + def get_identity_state(passed) -> tuple[str, bool]: """Returns the distinct id to use, and whether this is a personless event or not""" - stringified = stringify_id(passed) - if stringified and len(stringified): - return (stringified, False) + explicit = _explicit_distinct_id(passed) + if explicit: + return (explicit, False) context_id = get_context_distinct_id() if context_id: return (context_id, False) - return (str(uuid4()), True) - + return (str(_uuid7()), True) -def _stringify_event_uuid(value) -> str: - if isinstance(value, UUID): - return str(value) - - stringified = stringify_id(value) - if not stringified: - raise ValueError( - f"Invalid event uuid {value!r}. Expected a valid UUID string or uuid.UUID instance." - ) - try: - UUID(stringified) - except ValueError: - raise ValueError( - f"Invalid event uuid {value!r}. Expected a valid UUID string or uuid.UUID instance." - ) from None +def _group_identify_distinct_id(passed, group_type, group_key) -> str: + """The caller's id, else the context id, else one stable id per group. - return stringified + Ingestion creates a person for each new distinct id, so a random id + would add a person on every call. + """ + distinct_id, personless = get_identity_state(passed) + if personless: + return f"${group_type}_{group_key}" + return distinct_id def add_context_tags(properties): @@ -326,12 +343,24 @@ def add_context_tags(properties): context_tags.update(properties) properties = context_tags + return _add_context_session_id(properties) + + +def _add_context_session_id(properties): if "$session_id" not in properties and get_context_session_id(): properties["$session_id"] = get_context_session_id() - return properties +def _context_tag_defaults() -> dict[str, Any]: + """The current context's tags, as event property defaults.""" + current_context = _get_current_context() + if not current_context: + return {} + context_tags = current_context.collect_tags() + return {**context_tags, "$context_tags": set(context_tags.keys())} + + def no_throw(default_return=None): """ Decorator to prevent raising exceptions from public API methods. @@ -383,8 +412,14 @@ def wrapper(self, *args, **kwargs): # Correctness-required "$groups", "$process_person_profile", + # Option sources: legacy properties move into options after this + # allowlist runs, so dropping them would drop the option. + "$cookieless_mode", + "$ignore_sent_at", + "$product_tour_id", # Linkage / SDK identity "$session_id", + "$window_id", "$lib", "$lib_version", "$is_server", @@ -553,12 +588,6 @@ def _rule_attribution(details: Optional[FeatureFlag]) -> Optional[_RuleAttributi if _v4_field(metadata, "config_version") != 2: return None reason_code = (details.reason.code if details.reason else None) or None - return _rule_attribution_from_metadata(details, metadata, reason_code) - - -def _rule_attribution_from_metadata( - details: FeatureFlag, metadata: FlagMetadata, reason_code: Optional[str] -) -> _RuleAttribution: allowed_rule_types = _RULE_TYPES_BY_REASON_CODE.get(reason_code or "") if _v4_field(details, "failed") is True or allowed_rule_types is None: return _RuleAttribution(reason_code, None, None, None) @@ -741,112 +770,56 @@ def _capture_flag_events( ) if reported_flags is not None: - _capture_flag_called_event( - capture, - reported_flags, - feature_flag_reported_key, - distinct_id=distinct_id, - properties=properties, - capture_groups=capture_groups, - disable_geoip=disable_geoip, - has_experiment=has_experiment, - minimal_flag_called_events=minimal_flag_called_events, - attribution=attribution, - flag_identity=flag_identity, - ) - - _capture_experiment_exposure( - capture, - exposures_reported, - distinct_id=distinct_id, - key=key, - groups_key=groups_key, - properties=properties, - capture_groups=capture_groups, - disable_geoip=disable_geoip, - attribution=attribution, - flag_identity=flag_identity, - ) - - -def _capture_flag_called_event( - capture, - reported_flags, - feature_flag_reported_key, - *, - distinct_id, - properties, - capture_groups, - disable_geoip, - has_experiment, - minimal_flag_called_events, - attribution, - flag_identity, -) -> None: - if attribution is not None: - properties.pop("$feature_flag_reason", None) - properties.update(attribution.flag_called_properties()) - # Record the server's experiment signal when known, so minimization's impact - # can be measured by segmenting on it. - if has_experiment is not None: - properties["$feature_flag_has_experiment"] = has_experiment - - # Minimize iff the server-controlled gate is on AND the flag is known to have - # no linked experiment. Any missing signal (gate absent, has_experiment - # missing) fails safe to the full legacy shape. - should_minimize = minimal_flag_called_events and has_experiment is False - # Only thread the internal allowlist through when minimizing, so the - # full-property path's capture() call signature stays unchanged. - extra_capture_kwargs: Dict[str, Any] = {} - if should_minimize: - extra_capture_kwargs["_property_allowlist"] = ( - _MINIMAL_FLAG_CALLED_EVENT_PROPERTIES - if attribution is None - else _MINIMAL_V2_FLAG_CALLED_EVENT_PROPERTIES - ) - - if attribution is None: - # Config version 1 events are sent and deduped as before. - capture( - "$feature_flag_called", - distinct_id=distinct_id, - properties=properties, - groups=capture_groups, - disable_geoip=disable_geoip, - **extra_capture_kwargs, - ) - reported_flags.add(feature_flag_reported_key) - else: - _capture_once( - capture, - reported_flags, - feature_flag_reported_key, - "$feature_flag_called", - distinct_id=distinct_id, - properties=properties, - groups=capture_groups, - disable_geoip=disable_geoip, - _pinned_properties=_PinnedProperties( - _V2_FLAG_CALLED_PINNED, - {**attribution.flag_called_properties(), **flag_identity}, - ), - **extra_capture_kwargs, - ) + if attribution is not None: + properties.pop("$feature_flag_reason", None) + properties.update(attribution.flag_called_properties()) + # Record the server's experiment signal when known, so minimization's impact + # can be measured by segmenting on it. + if has_experiment is not None: + properties["$feature_flag_has_experiment"] = has_experiment + + # Minimize iff the server-controlled gate is on AND the flag is known to have + # no linked experiment. Any missing signal (gate absent, has_experiment + # missing) fails safe to the full legacy shape. + should_minimize = minimal_flag_called_events and has_experiment is False + # Only thread the internal allowlist through when minimizing, so the + # full-property path's capture() call signature stays unchanged. + extra_capture_kwargs: Dict[str, Any] = {} + if should_minimize: + extra_capture_kwargs["_property_allowlist"] = ( + _MINIMAL_FLAG_CALLED_EVENT_PROPERTIES + if attribution is None + else _MINIMAL_V2_FLAG_CALLED_EVENT_PROPERTIES + ) + if attribution is None: + # Config version 1 events are sent and deduped as before. + capture( + "$feature_flag_called", + distinct_id=distinct_id, + properties=properties, + groups=capture_groups, + disable_geoip=disable_geoip, + **extra_capture_kwargs, + ) + reported_flags.add(feature_flag_reported_key) + else: + _capture_once( + capture, + reported_flags, + feature_flag_reported_key, + "$feature_flag_called", + distinct_id=distinct_id, + properties=properties, + groups=capture_groups, + disable_geoip=disable_geoip, + _pinned_properties=_PinnedProperties( + _V2_FLAG_CALLED_PINNED, + {**attribution.flag_called_properties(), **flag_identity}, + ), + **extra_capture_kwargs, + ) -def _capture_experiment_exposure( - capture, - exposures_reported, - *, - distinct_id, - key, - groups_key, - properties, - capture_groups, - disable_geoip, - attribution, - flag_identity, -) -> None: if attribution is None or attribution.variant_key is None: return @@ -906,13 +879,11 @@ def __init__( send, flush_at, flush_interval, - gzip, max_retries, timeout, historical_migration, endpoint, max_msg_size, - capture_mode, capture_compression, sdk_info, eager_start, @@ -924,13 +895,11 @@ def __init__( self.send = send self.flush_at = flush_at self.flush_interval = flush_interval - self.gzip = gzip self.max_retries = max_retries self.timeout = timeout self.historical_migration = historical_migration self.endpoint = endpoint self.max_msg_size = max_msg_size - self.capture_mode = capture_mode self.capture_compression = capture_compression self.sdk_info = sdk_info self._max_queue_size = max_queue_size @@ -959,13 +928,11 @@ def _start_locked(self) -> None: on_error=self.on_error, flush_at=self.flush_at, flush_interval=self.flush_interval, - gzip=self.gzip, retries=self.max_retries, timeout=self.timeout, historical_migration=self.historical_migration, endpoint=self.endpoint, max_msg_size=self.max_msg_size, - capture_mode=self.capture_mode, capture_compression=self.capture_compression, ) consumer._sdk_info = self.sdk_info @@ -1102,29 +1069,6 @@ def join(self) -> None: ) errors.append(error) - self._stop_consumers(errors) - try: - self.discard_undrainable_queued_work() - except Exception as error: - self.log.exception( - "Failed to discard queued %s lane work during lifecycle cleanup", - self.name, - ) - errors.append(error) - if drain_requested: - try: - self._drain_signal.complete() - except Exception as error: - self.log.exception( - "Failed to complete %s lane drain during lifecycle cleanup", - self.name, - ) - errors.append(error) - - if errors: - raise errors[0] - - def _stop_consumers(self, errors: list[Exception]) -> None: for consumer in self.consumers: try: consumer._pause(drain=True) @@ -1146,6 +1090,26 @@ def _stop_consumers(self, errors: list[Exception]) -> None: self.name, ) errors.append(error) + try: + self.discard_undrainable_queued_work() + except Exception as error: + self.log.exception( + "Failed to discard queued %s lane work during lifecycle cleanup", + self.name, + ) + errors.append(error) + if drain_requested: + try: + self._drain_signal.complete() + except Exception as error: + self.log.exception( + "Failed to complete %s lane drain during lifecycle cleanup", + self.name, + ) + errors.append(error) + + if errors: + raise errors[0] def reset_sync_send_state_after_fork(self) -> None: """Replace sync-send state inherited from threads that did not survive fork.""" @@ -1206,13 +1170,13 @@ def __init__( self, project_api_key: str, host=None, + *, debug=False, max_queue_size=10000, send=True, on_error=None, flush_at=100, flush_interval=5.0, - gzip=False, max_retries=3, sync_mode=False, timeout: float = 15, @@ -1226,6 +1190,7 @@ def __init__( feature_flags_request_timeout_seconds: float = 3, feature_flags_request_max_retries=1, super_properties=None, + super_options=None, enable_exception_autocapture=False, log_captured_exceptions=False, project_root=None, @@ -1244,13 +1209,14 @@ def __init__( exception_autocapture_bucket_size=ExceptionCapture.DEFAULT_BUCKET_SIZE, exception_autocapture_refill_rate=ExceptionCapture.DEFAULT_REFILL_RATE, exception_autocapture_refill_interval_seconds=ExceptionCapture.DEFAULT_REFILL_INTERVAL_SECONDS, - capture_mode: Optional[Union[CaptureMode, str]] = None, capture_compression: Optional[Union[CaptureCompression, str]] = None, + capture_ai_compression: Optional[Union[CaptureCompression, str]] = None, + capture_ai_max_queue_size: int = 1000, + capture_ai_timeout: float = 30, + capture_ai_max_event_bytes: int = AI_MAX_MSG_SIZE, secret_key=None, metrics: Optional[dict] = None, enable_full_ai_capture=False, - # Appended rather than grouped with the other `capture_*` options so - # existing positional arguments keep their slots. capture_trace_context=False, _use_ai_lane=False, _enable_multimodal_capture=False, @@ -1270,17 +1236,21 @@ def __init__( the corresponding ingestion host. debug: Enable verbose SDK logging and re-raise errors from public API methods. - max_queue_size: Maximum number of events buffered before upload. + max_queue_size: Maximum number of analytics events buffered before + upload. AI events use ``capture_ai_max_queue_size``. send: If False, queueing succeeds but events are not sent. - on_error: Optional callback invoked by background consumers when an - upload fails. Keep it short and non-blocking. Calling lifecycle + on_error: Optional callback ``(error, batch)`` invoked when an upload + fails: by background consumers, or on the calling thread in + ``sync_mode``. Capture failures arrive as ``CaptureError``. + Without it, each failed batch logs one aggregate line. A capture + that fails inside the callback logs that line instead of calling + it again. Keep it short and non-blocking. Calling lifecycle methods directly is safe and deferred, but do not start another thread or task that calls ``flush()``, ``join()``, or ``shutdown()`` and then wait for it from the callback. flush_at: Number of queued events that triggers a batch upload. flush_interval: Maximum seconds a background consumer waits before flushing a partial batch. - gzip: Whether to gzip event upload payloads. max_retries: Number of upload retries. Values below 0 are treated as 0. sync_mode: If True, send each event synchronously instead of using background worker threads. This blocks the calling thread; in @@ -1299,10 +1269,13 @@ def __init__( accepts a Project Secret API Key. disabled: If True, disable captures and API requests. Useful in tests. disable_geoip: Whether to disable server-side GeoIP enrichment. - Defaults to True. + Defaults to True. Events get ``$geoip_disable`` only when the + event, context tags and ``super_properties`` leave it unset. is_server: Whether events are emitted from a server-side runtime. Defaults to True; set to False when using the SDK as a client/CLI - so the device OS is attributed to the person normally. + so the device OS is attributed to the person normally. Events + get ``$is_server`` only when the event, context tags and + ``super_properties`` leave it unset. historical_migration: Mark events as historical migration imports. feature_flags_request_timeout_seconds: Timeout in seconds for feature flag and remote config requests. @@ -1320,7 +1293,19 @@ def __init__( Set to 0 when a job runner already retries the send. migrated_from: The email provider you moved from, such as ``"resend"``. ``emails`` sends it with every request. - super_properties: Properties merged into every captured event. + super_properties: Properties for every captured event. They fill + only keys the event leaves unset, before ``before_send`` runs. + ``$set``, ``$set_once``, ``$groups`` and ``$group_set`` fill + one level deep. An event's own properties and context tags + override them, and ``before_send`` can change or remove them. + super_options: Capture options for every captured event, such as + ``{"cookieless_mode": True}``. They fill only options the event + leaves unset, before ``before_send`` runs. An event's own + ``options`` and context options override them, and + ``before_send`` can change them. They never set + ``process_person_profile`` on identify-style events, such as + ``$identify`` or ``$set``, whose distinct ID the SDK did not + generate: those default it to ``True``. enable_exception_autocapture: Automatically capture uncaught exceptions. log_captured_exceptions: Also log exceptions captured by error @@ -1329,13 +1314,17 @@ def __init__( captured exceptions. Defaults to the current working directory. privacy_mode: For AI observability, capture usage metadata without prompt inputs or outputs. - enable_full_ai_capture: 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. + enable_full_ai_capture: Capture full AI content in PostHog AI + wrapper events: skips string truncation and passes media + (base64/data URIs) through unredacted. ``privacy_mode`` always + wins. Wrapper events use the AI capture endpoint whether or not + this is set. Defaults to False. before_send: Optional callback that can modify or drop events before - upload. Return ``None`` to drop an event. + upload. Return ``None`` to drop an event. Context tags, + context options, ``super_properties``, ``super_options`` and + the values the SDK adds, such as ``$is_server``, + ``$geoip_disable`` and ``$os``, fill in before it runs, so it + can change or remove them. flag_fallback_cache_url: Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL. enable_local_evaluation: Whether to poll feature flag definitions for @@ -1347,12 +1336,17 @@ def __init__( capture_trace_context: 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 + ``capture_ai()``, so they can be correlated with backend traces. They fill + after context tags and ``super_properties``, before ``before_send``. A + ``$trace_id`` or ``$span_id`` from the event, a context tag or + ``super_properties`` stops the SDK adding either ID. Exception events (``capture_exception``) always attach these IDs regardless of this setting. Defaults to False. - traces: Config dict for distributed tracing: ``service_name``, - ``service_version``, ``environment``, ``resource_attributes``, + traces: Config dict for distributed tracing. Non-empty string values for + ``service.name``, ``service.version`` and ``deployment.environment`` + in ``resource_attributes`` take precedence over ``service_name``, + ``service_version`` and ``environment``, respectively. Options include + ``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), @@ -1361,10 +1355,26 @@ def __init__( 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. + raises drops the span. The span dict has ``name``, ``kind``, + ``status``, ``attributes``, ``events``, ``start_time_ns``, + ``end_time_ns``, ``trace_id``, ``span_id`` and + ``parent_span_id``, and its attributes are plain Python values. + The hook runs after ``posthogDistinctId`` and ``sessionId`` are + attached, so it can scrub them. It must be a regular function. + An ``async`` hook drops every span. In a list of hooks, the + first one to return ``None`` stops the chain. An entry that + isn't callable turns tracing off for the client. Past a + per-span cap, the earliest attributes and events are kept and + the span reports how many were dropped. ``posthogDistinctId`` + and ``sessionId`` don't count toward the attribute cap and are + never dropped. ``max_attribute_value_length`` also applies to + strings nested in lists and dictionaries. All caps are applied + again after ``before_span_send``. Spans beyond + ``max_queue_size`` are dropped. An invalid value falls back to + its default with a warning. 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. code_variables_mask_patterns: Variable-name patterns to mask when capturing code variables. code_variables_ignore_patterns: Variable-name patterns to omit when @@ -1389,16 +1399,27 @@ def __init__( interval for each exception type's bucket. exception_autocapture_refill_interval_seconds: Seconds between token refills for autocaptured exception rate limiting. - capture_mode: Capture wire protocol to use. Defaults to - ``CaptureMode.V0`` (legacy ``/batch/``). Set ``CaptureMode.V1`` - (or pass the string ``"v1"``) to opt into - ``/i/v1/analytics/events``. When omitted, the - ``POSTHOG_CAPTURE_MODE`` env var is consulted, then ``V0``. - capture_compression: Request-body compression for capture-v1 uploads - (ignored in V0, which uses ``gzip``). ``CaptureCompression.GZIP`` - or ``DEFLATE`` (or the strings ``"gzip"``/``"deflate"``). When - omitted, the ``POSTHOG_CAPTURE_COMPRESSION`` env var is consulted, - then the legacy ``gzip`` flag, then no compression. + capture_compression: Request-body compression for ``capture()`` + uploads. ``CaptureCompression.GZIP``, ``DEFLATE`` or ``ZSTD`` + (or the strings ``"gzip"``, ``"deflate"`` or ``"zstd"``). + ``ZSTD`` needs ``pip install posthog[zstd]``. When omitted, the + ``POSTHOG_CAPTURE_COMPRESSION`` env var is consulted, then no + compression. + capture_ai_compression: Request-body compression for + ``capture_ai()`` uploads, set independently of + ``capture_compression``. Defaults to no compression, and the + env var does not apply. ``CaptureCompression.ZSTD`` suits large + AI payloads. + capture_ai_max_queue_size: Maximum number of AI events buffered + before upload. Defaults to 1000, lower than ``max_queue_size`` + because AI events are much larger. + capture_ai_timeout: Seconds allowed for one AI upload request. + Defaults to 30, longer than ``timeout`` because AI batches are + much larger. + capture_ai_max_event_bytes: Largest serialized AI event the SDK + sends; a larger one is dropped with an error log. Defaults to + the AI endpoint's ceiling plus envelope headroom, and may only + be lowered. Examples: ```python @@ -1445,7 +1466,6 @@ def __init__( self.raw_host = normalize_host(host) self.host = determine_server_host(host) self._duplicate_client_registry_key: Optional[tuple[str, str]] = None - self.gzip = gzip self.timeout = timeout self.max_retries = max(0, max_retries) self._feature_flags: Optional[list[Any]] = ( @@ -1492,7 +1512,9 @@ def __init__( _BackgroundEventLoopRunner ] = None self._flag_definition_cache_provider_async_runner_lock = threading.Lock() - self.disabled = disabled or not self.api_key + self.disabled = ( + disabled or not self.api_key or _is_personal_api_key(self.api_key) + ) self.disable_geoip = disable_geoip self._metrics_config = metrics self._metrics: Optional[PostHogMetrics] = None @@ -1513,19 +1535,27 @@ def __init__( ) self.is_server = is_server self.historical_migration = historical_migration - # Selects the capture wire protocol (V0 legacy `/batch/` vs V1 - # `/i/v1/analytics/events`). Resolved here so the env-var fallback is - # applied once; V0 is the default and keeps upgrades transparent. - self.capture_mode = _resolve_capture_mode(capture_mode) self._library_id = "posthog-python" self._library_version = VERSION self._sdk_info = f"{self._library_id}/{self._library_version}" - # v1-only request compression; falls back to the legacy `gzip` flag when - # neither the kwarg nor POSTHOG_CAPTURE_COMPRESSION is set. - self.capture_compression = _resolve_capture_compression( - capture_compression, gzip_fallback=gzip + self.capture_compression = _resolve_capture_compression(capture_compression) + self.capture_ai_compression = _resolve_capture_ai_compression( + capture_ai_compression + ) + capture_ai_max_queue_size = _positive_config_value( + "capture_ai_max_queue_size", capture_ai_max_queue_size, integer=True + ) + capture_ai_timeout = _positive_config_value( + "capture_ai_timeout", capture_ai_timeout + ) + capture_ai_max_event_bytes = _positive_config_value( + "capture_ai_max_event_bytes", + capture_ai_max_event_bytes, + integer=True, + maximum=AI_MAX_MSG_SIZE, ) self.super_properties = super_properties + self.super_options = super_options # Release id from POSTHOG_RELEASE_ID, attached to every event. Resolved # here so the env var is read once per client. self._release_id = _resolve_release_id() @@ -1550,111 +1580,6 @@ def __init__( self._logged_untyped_flags_response = False self.capture_trace_context = capture_trace_context - self._configure_exception_properties( - capture_exception_code_variables, - code_variables_mask_patterns, - code_variables_ignore_patterns, - code_variables_mask_url_credentials, - code_variables_detect_secrets, - in_app_modules, - project_root, - ) - - self._configure_credentials( - personal_api_key, - secret_key, - app_host, - email_request_timeout_seconds, - email_request_max_retries, - migrated_from, - ) - self._configure_logging(debug) - - self._set_before_send(before_send) - - if self.enable_exception_autocapture: - self.exception_capture = ExceptionCapture( - self, - rate_limiting_enabled=self.enable_exception_autocapture_rate_limiting, - bucket_size=self.exception_autocapture_bucket_size, - refill_rate=self.exception_autocapture_refill_rate, - refill_interval_seconds=self.exception_autocapture_refill_interval_seconds, - ) - - if not sync_mode and send: - # On program exit, allow the consumer threads to exit cleanly. - # This prevents exceptions and a messy shutdown when the - # interpreter is destroyed before the daemon threads finish - # execution. Exit performs only a short best-effort flush; call - # flush() or shutdown() explicitly when blocking completion matters. - atexit.register(self._atexit) - - lane_defaults = dict( - api_key=self.api_key, - host=self.host, - on_error=on_error, - max_queue_size=max_queue_size, - thread_count=thread, - send=send, - flush_at=flush_at, - flush_interval=flush_interval, - gzip=gzip, - max_retries=self.max_retries, - timeout=timeout, - historical_migration=historical_migration, - sdk_info=self._sdk_info, - ) - self._analytics_lane = _Lane( - name="analytics", - **lane_defaults, - endpoint=EVENTS_ENDPOINT, - max_msg_size=MAX_MSG_SIZE, - capture_mode=self.capture_mode, - capture_compression=self.capture_compression, - eager_start=not sync_mode, - ) - # The AI lane is pinned to the v0 submitter: the AI endpoint has no v1 - # form, and this keeps multi-MB AI events away from capture v1's - # smaller caps. The `capture_compression` pin is inert on v0 — its wire - # compression is the `gzip` flag, inherited from client config. Lazy - # start, so the many clients that never emit AI events pay for no - # extra threads. - self._ai_lane = _Lane( - name="ai", - **lane_defaults, - endpoint=AI_EVENTS_ENDPOINT, - max_msg_size=AI_MAX_MSG_SIZE, - capture_mode=CaptureMode.V0, - capture_compression=CaptureCompression.NONE, - eager_start=False, - ) - self._lanes = [self._analytics_lane, self._ai_lane] - - self._metrics_autocapture: Optional[Any] = None - self._metrics_autocapture_tried = False - self._start_metrics_autocapture_once(metrics) - - self._register_fork_handler() - - self._warn_if_duplicate_async_client() - - def _register_fork_handler(self) -> None: - if hasattr(os, "register_at_fork"): - weak_self = weakref.ref(self) - os.register_at_fork( - after_in_child=lambda: Client._reinit_after_fork_weak(weak_self) - ) - - def _configure_exception_properties( - self, - capture_exception_code_variables, - code_variables_mask_patterns, - code_variables_ignore_patterns, - code_variables_mask_url_credentials, - code_variables_detect_secrets, - in_app_modules, - project_root, - ) -> None: self.capture_exception_code_variables = capture_exception_code_variables self.code_variables_mask_patterns = ( code_variables_mask_patterns @@ -1686,21 +1611,12 @@ def _configure_exception_properties( self.project_root = project_root - def _configure_credentials( - self, - personal_api_key, - secret_key, - app_host, - email_request_timeout_seconds, - email_request_max_retries, - migrated_from, - ) -> None: if personal_api_key is not None and secret_key is None: warnings.warn( "`personal_api_key` is deprecated; use `secret_key` instead. " "`secret_key` accepts a Personal API Key or a Project Secret API Key.", DeprecationWarning, - stacklevel=3, + stacklevel=2, ) elif secret_key is not None and personal_api_key is not None: self.log.warning( @@ -1721,8 +1637,6 @@ def _configure_credentials( self.email_request_timeout_seconds = email_request_timeout_seconds self.email_request_max_retries = email_request_max_retries self.migrated_from = migrated_from - - def _configure_logging(self, debug) -> None: if debug: # Ensures that debug level messages are logged when debug mode is on. # Otherwise, defaults to WARNING level. See https://docs.python.org/3/howto/logging.html#what-happens-if-no-configuration-is-provided @@ -1735,6 +1649,78 @@ def _configure_logging(self, debug) -> None: self.log.error( "api_key is empty after trimming whitespace; check your project API key" ) + elif _is_personal_api_key(self.api_key): + self.log.error( + "api_key is a personal API key (phx_...), not a project API key; " + "PostHog is disabled. Use the project API key (phc_...)." + ) + + self._set_before_send(before_send) + + if self.enable_exception_autocapture: + self.exception_capture = ExceptionCapture( + self, + rate_limiting_enabled=self.enable_exception_autocapture_rate_limiting, + bucket_size=self.exception_autocapture_bucket_size, + refill_rate=self.exception_autocapture_refill_rate, + refill_interval_seconds=self.exception_autocapture_refill_interval_seconds, + ) + + if not sync_mode and send: + # On program exit, allow the consumer threads to exit cleanly. + # This prevents exceptions and a messy shutdown when the + # interpreter is destroyed before the daemon threads finish + # execution. Exit performs only a short best-effort flush; call + # flush() or shutdown() explicitly when blocking completion matters. + atexit.register(self._atexit) + + lane_defaults = dict( + api_key=self.api_key, + host=self.host, + on_error=on_error, + thread_count=thread, + send=send, + flush_at=flush_at, + flush_interval=flush_interval, + max_retries=self.max_retries, + historical_migration=historical_migration, + sdk_info=self._sdk_info, + ) + self._analytics_lane = _Lane( + name="analytics", + **lane_defaults, + max_queue_size=max_queue_size, + timeout=timeout, + endpoint=_CAPTURE_V1_PATH, + max_msg_size=MAX_MSG_SIZE, + capture_compression=self.capture_compression, + eager_start=not sync_mode, + ) + # A separate endpoint keeps multi-MB AI events off the analytics caps. + # Lazy start, so clients that never send AI events pay for no threads. + self._ai_lane = _Lane( + name="ai", + **lane_defaults, + max_queue_size=capture_ai_max_queue_size, + timeout=capture_ai_timeout, + endpoint=_CAPTURE_AI_V1_PATH, + max_msg_size=capture_ai_max_event_bytes, + capture_compression=self.capture_ai_compression, + eager_start=False, + ) + self._lanes = [self._analytics_lane, self._ai_lane] + + self._metrics_autocapture: Optional[Any] = None + self._metrics_autocapture_tried = False + self._start_metrics_autocapture_once(metrics) + + if hasattr(os, "register_at_fork"): + weak_self = weakref.ref(self) + os.register_at_fork( + after_in_child=lambda: Client._reinit_after_fork_weak(weak_self) + ) + + self._warn_if_duplicate_async_client() def _start_metrics_autocapture_once(self, metrics_config: Any) -> None: """Starts metrics autocapture when the ``metrics`` option asks for it. A @@ -1811,19 +1797,6 @@ def run_as_callback(sample): before_send=before_send, ) - def _set_library_identity(self, library_id: str, library_version: str) -> None: - """Override the SDK identity stamped on events and outbound requests.""" - self._library_id = library_id - self._library_version = library_version - self._sdk_info = f"{library_id}/{library_version}" - for lane in self._lanes: - lane.sdk_info = self._sdk_info - for consumer in lane.consumers: - consumer._sdk_info = self._sdk_info - - def _request_identity_kwargs(self) -> Dict[str, str]: - return {"_user_agent": self._sdk_info} if self._sdk_info != _USER_AGENT else {} - _emails: Optional[Emails] = None @property @@ -2011,12 +1984,45 @@ def get_tags(self) -> Dict[str, Any]: """ return _context_get_tags() - def identify_context(self, distinct_id: str) -> None: + def set_context_option(self, key: str, value: Any) -> None: """ - Identify the current context with a distinct ID. + Set a capture option for every event captured within the current context. + + Context options fill options an event leaves unset, before + ``before_send`` runs, so the hook sees them. They override + ``super_options``. An event's own ``options`` override them, and + ``before_send`` can change them. They never set + ``process_person_profile`` on identify-style events, such as + ``$identify`` or ``$set``, whose distinct ID the SDK did not generate: + those default it to ``True``. Args: - distinct_id: The distinct ID to associate with the current context and its children. + key: The option name, such as ``"process_person_profile"``. + value: The option value, sent as given. + + Category: + Contexts + """ + _context_set_context_option(key, value) + + def get_context_options(self) -> Dict[str, Any]: + """ + Get all capture options from the current context. + + Returns: + Dict of all capture options in the current context. + + Category: + Contexts + """ + return _context_get_context_options() + + def identify_context(self, distinct_id: str) -> None: + """ + Identify the current context with a distinct ID. + + Args: + distinct_id: The distinct ID to associate with the current context and its children. Category: Contexts @@ -2258,51 +2264,6 @@ def _get_flags_decision( if self.disabled: return normalize_flags_response({}) - request_data = self._flags_request_data( - distinct_id, - groups, - person_properties, - group_properties, - disable_geoip, - device_id, - ) - - if flag_keys_to_evaluate: - request_data["flag_keys_to_evaluate"] = flag_keys_to_evaluate - if self._sdk_info != _USER_AGENT: - request_data["_user_agent"] = self._sdk_info - - resp_data = flags( - self.api_key, - self.host, - timeout=self.feature_flags_request_timeout_seconds, - max_retries=self.feature_flags_request_max_retries, - **request_data, - ) - - if not self._logged_untyped_flags_response and _has_untyped_flag_records( - resp_data - ): - self._logged_untyped_flags_response = True - self.log.info(_UNTYPED_FLAGS_RESPONSE_MESSAGE) - response = normalize_flags_response(resp_data) - # Server-controlled gate for minimal $feature_flag_called events. Only the - # v2 response shape carries it; absent (legacy shape, older server, team - # not gated) means False. - self._minimal_flag_called_events = ( - response.get("minimalFlagCalledEvents") is True - ) - return response - - def _flags_request_data( - self, - distinct_id, - groups, - person_properties, - group_properties, - disable_geoip, - device_id, - ): groups = groups or {} person_properties = person_properties or {} group_properties = group_properties or {} @@ -2328,7 +2289,30 @@ def _flags_request_data( "device_id": device_id, } - return request_data + if flag_keys_to_evaluate: + request_data["flag_keys_to_evaluate"] = flag_keys_to_evaluate + + resp_data = flags( + self.api_key, + self.host, + timeout=self.feature_flags_request_timeout_seconds, + max_retries=self.feature_flags_request_max_retries, + **request_data, + ) + + if not self._logged_untyped_flags_response and _has_untyped_flag_records( + resp_data + ): + self._logged_untyped_flags_response = True + self.log.info(_UNTYPED_FLAGS_RESPONSE_MESSAGE) + response = normalize_flags_response(resp_data) + # Server-controlled gate for minimal $feature_flag_called events. Only the + # v2 response shape carries it; absent (legacy shape, older server, team + # not gated) means False. + self._minimal_flag_called_events = ( + response.get("minimalFlagCalledEvents") is True + ) + return response @no_throw() def capture( @@ -2346,14 +2330,27 @@ def capture( uuid: A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID. - groups: A dictionary of group information. + groups: A dictionary of group information. It merges into a + ``$groups`` property and wins key by key. flags: A FeatureFlagEvaluations snapshot from evaluate_flags(). The exact values from the snapshot are attached with no extra /flags request. send_feature_flags: Deprecated. Prefer flags=... from evaluate_flags(). When truthy, evaluates flags during capture and attaches them to the event. - disable_geoip: Whether to disable GeoIP for this event. + disable_geoip: Whether to disable GeoIP for this event. It wins + over a ``$geoip_disable`` in context tags or + ``super_properties``. A ``$geoip_disable`` property in this + call's ``properties`` wins over it. + options: Capture options for this event, such as + ``{"process_person_profile": False}``. Sent as given, for + PostHog to validate. They override context options and + ``super_options``, which fill in before ``before_send`` runs. + An option overrides its legacy ``$`` property, such as + ``$process_person_profile``. A ``None`` option counts as unset. + An identify-style event, such as ``$identify`` or ``$set``, + gets ``process_person_profile: True`` when this call leaves it + unset, unless the SDK generated its distinct ID. Examples: ```python @@ -2409,7 +2406,7 @@ def capture_ai( Category: Capture """ - if not event.startswith("$ai_"): + if isinstance(event, str) and not event.startswith("$ai_"): self.log.debug( "capture_ai called with non-AI event name %r; routing it to the AI endpoint anyway.", event, @@ -2428,18 +2425,24 @@ def _capture( flags_snapshot = kwargs.get("flags", None) send_feature_flags = kwargs.get("send_feature_flags", False) disable_geoip = kwargs.get("disable_geoip", None) + options = _event_options(kwargs.get("options", None)) # Internal, set for minimal $feature_flag_called events: a strict allowlist # applied to the fully-enriched properties dict just before enqueueing. property_allowlist = kwargs.get("_property_allowlist", None) pinned_properties = kwargs.get("_pinned_properties", None) before_send_drops = kwargs.get("_before_send_drops", None) - properties = self._capture_properties(properties) + properties = dict(properties or {}) - (distinct_id, personless) = get_identity_state(distinct_id) + trace_properties = ( + _get_current_otel_span_properties() + if self.capture_trace_context or kwargs.get("_capture_trace_context") + else None + ) + + properties = _add_context_session_id(properties) - if personless and "$process_person_profile" not in properties: - properties["$process_person_profile"] = False + (distinct_id, personless) = get_identity_state(distinct_id) msg = { "properties": properties, @@ -2447,10 +2450,11 @@ def _capture( "distinct_id": distinct_id, "event": event, "uuid": uuid, + "options": options, } if groups: - properties["$groups"] = groups + _merge_groups(properties, groups) extra_properties: dict[str, Any] = {} @@ -2466,117 +2470,94 @@ def _capture( ) extra_properties = flags_snapshot._get_event_properties() else: - extra_properties = self._capture_legacy_flag_properties( - distinct_id, groups, disable_geoip, send_feature_flags - ) + feature_variants: Optional[dict[str, Union[bool, str]]] = {} + + # Parse and normalize send_feature_flags parameter + flag_options = self._parse_send_feature_flags(send_feature_flags) + + if flag_options["should_send"]: + warnings.warn( + "`send_feature_flags` is deprecated and will be removed in a future major " + "version. Pass a `flags` snapshot from `posthog.evaluate_flags(...)` instead " + "— it avoids a second `/flags` request per capture and guarantees the event " + "carries the exact flag values your code branched on.", + DeprecationWarning, + stacklevel=2, + ) + try: + if flag_options["only_evaluate_locally"] is True: + # Local evaluation explicitly requested + feature_variants = self.get_all_flags( + distinct_id, + groups=(groups or {}), + person_properties=flag_options["person_properties"], + group_properties=flag_options["group_properties"], + disable_geoip=disable_geoip, + only_evaluate_locally=True, + flag_keys_to_evaluate=flag_options["flag_keys_filter"], + ) + elif flag_options["only_evaluate_locally"] is False: + # Remote evaluation explicitly requested + feature_variants = self.get_feature_variants( + distinct_id, + groups, + person_properties=flag_options["person_properties"], + group_properties=flag_options["group_properties"], + disable_geoip=disable_geoip, + flag_keys_to_evaluate=flag_options["flag_keys_filter"], + ) + elif self.feature_flags: + # Local flags available, prefer local evaluation + feature_variants = self.get_all_flags( + distinct_id, + groups=(groups or {}), + person_properties=flag_options["person_properties"], + group_properties=flag_options["group_properties"], + disable_geoip=disable_geoip, + only_evaluate_locally=True, + flag_keys_to_evaluate=flag_options["flag_keys_filter"], + ) + else: + # Fall back to remote evaluation + feature_variants = self.get_feature_variants( + distinct_id, + groups, + person_properties=flag_options["person_properties"], + group_properties=flag_options["group_properties"], + disable_geoip=disable_geoip, + flag_keys_to_evaluate=flag_options["flag_keys_filter"], + ) + except Exception as e: + self.log.exception( + f"[FEATURE FLAGS] Unable to get feature variants: {e}" + ) - if extra_properties: - properties = {**extra_properties, **properties} - msg["properties"] = properties + for feature, variant in (feature_variants or {}).items(): + extra_properties[f"$feature/{feature}"] = variant + + active_feature_flags = [ + key + for (key, value) in (feature_variants or {}).items() + if value is not False + ] + if active_feature_flags: + extra_properties["$active_feature_flags"] = active_feature_flags return self._enqueue( msg, disable_geoip, lane, property_allowlist=property_allowlist, + context_properties=_context_tag_defaults(), + context_options=_context_get_context_options(), + personless=personless, + system_properties=system_context(), + flag_properties=extra_properties, + trace_properties=trace_properties, pinned_properties=pinned_properties, before_send_drops=before_send_drops, ) - def _capture_properties(self, properties): - properties = {**(properties or {}), **system_context()} - - if self.capture_trace_context: - properties = {**_get_current_otel_span_properties(), **properties} - - properties = add_context_tags(properties) - assert properties is not None # Type hint for mypy - return properties - - def _capture_legacy_flag_properties( - self, distinct_id, groups, disable_geoip, send_feature_flags - ): - extra_properties: dict[str, Any] = {} - feature_variants: Optional[dict[str, Union[bool, str]]] = {} - - # Parse and normalize send_feature_flags parameter - flag_options = self._parse_send_feature_flags(send_feature_flags) - - if flag_options["should_send"]: - warnings.warn( - "`send_feature_flags` is deprecated and will be removed in a future major " - "version. Pass a `flags` snapshot from `posthog.evaluate_flags(...)` instead " - "— it avoids a second `/flags` request per capture and guarantees the event " - "carries the exact flag values your code branched on.", - DeprecationWarning, - stacklevel=3, - ) - try: - feature_variants = self._evaluate_capture_flags( - distinct_id, groups, disable_geoip, flag_options - ) - except Exception as e: - self.log.exception( - f"[FEATURE FLAGS] Unable to get feature variants: {e}" - ) - - for feature, variant in (feature_variants or {}).items(): - extra_properties[f"$feature/{feature}"] = variant - - active_feature_flags = [ - key - for (key, value) in (feature_variants or {}).items() - if value is not False - ] - if active_feature_flags: - extra_properties["$active_feature_flags"] = active_feature_flags - - return extra_properties - - def _evaluate_capture_flags(self, distinct_id, groups, disable_geoip, flag_options): - if flag_options["only_evaluate_locally"] is True: - # Local evaluation explicitly requested - return self.get_all_flags( - distinct_id, - groups=(groups or {}), - person_properties=flag_options["person_properties"], - group_properties=flag_options["group_properties"], - disable_geoip=disable_geoip, - only_evaluate_locally=True, - flag_keys_to_evaluate=flag_options["flag_keys_filter"], - ) - elif flag_options["only_evaluate_locally"] is False: - # Remote evaluation explicitly requested - return self.get_feature_variants( - distinct_id, - groups, - person_properties=flag_options["person_properties"], - group_properties=flag_options["group_properties"], - disable_geoip=disable_geoip, - flag_keys_to_evaluate=flag_options["flag_keys_filter"], - ) - elif self.feature_flags: - # Local flags available, prefer local evaluation - return self.get_all_flags( - distinct_id, - groups=(groups or {}), - person_properties=flag_options["person_properties"], - group_properties=flag_options["group_properties"], - disable_geoip=disable_geoip, - only_evaluate_locally=True, - flag_keys_to_evaluate=flag_options["flag_keys_filter"], - ) - else: - # Fall back to remote evaluation - return self.get_feature_variants( - distinct_id, - groups, - person_properties=flag_options["person_properties"], - group_properties=flag_options["group_properties"], - disable_geoip=disable_geoip, - flag_keys_to_evaluate=flag_options["flag_keys_filter"], - ) - def _parse_send_feature_flags(self, send_feature_flags) -> SendFeatureFlagsOptions: """ Parse and normalize send_feature_flags parameter into a standard format. @@ -2662,9 +2643,12 @@ def set(self, **kwargs: Unpack[OptionalSetArgs]) -> Optional[str]: "$set": properties, "event": "$set", "uuid": uuid, + "options": _event_options(kwargs.get("options", None)), } - return self._enqueue(msg, disable_geoip) + return self._enqueue( + msg, disable_geoip, context_options=_context_get_context_options() + ) @no_throw() def set_once(self, **kwargs: Unpack[OptionalSetArgs]) -> Optional[str]: @@ -2711,9 +2695,12 @@ def set_once(self, **kwargs: Unpack[OptionalSetArgs]) -> Optional[str]: "$set_once": properties, "event": "$set_once", "uuid": uuid, + "options": _event_options(kwargs.get("options", None)), } - return self._enqueue(msg, disable_geoip) + return self._enqueue( + msg, disable_geoip, context_options=_context_get_context_options() + ) @no_throw() def group_identify( @@ -2725,6 +2712,7 @@ def group_identify( uuid: Optional[Union[str, UUID]] = None, disable_geoip: Optional[bool] = None, distinct_id: Optional[ID_TYPES] = None, + options: Optional[Dict[str, Any]] = None, ) -> Optional[str]: """ Identify a group and set its properties. @@ -2742,6 +2730,10 @@ def group_identify( ignored and replaced with a newly generated UUID. disable_geoip: Whether to disable GeoIP for this event. distinct_id: The distinct ID of the user performing the action. + Falls back to the context distinct ID, then to + ``$_``. + options: Capture options for this event, sent as given. + ``process_person_profile`` is ``True`` unless this call sets it. Examples: ```python @@ -2770,8 +2762,7 @@ def group_identify( properties = properties or {} - # group_identify is purposefully always personful - distinct_id = get_identity_state(distinct_id)[0] + distinct_id = _group_identify_distinct_id(distinct_id, group_type, group_key) msg: Dict[str, Any] = { "event": "$groupidentify", @@ -2783,13 +2774,17 @@ def group_identify( "distinct_id": distinct_id, "timestamp": timestamp, "uuid": uuid, + "options": _event_options(options), } - # NOTE - group_identify doesn't generally use context properties - should it? - if get_context_session_id(): - msg["properties"]["$session_id"] = str(get_context_session_id()) - - return self._enqueue(msg, disable_geoip) + # No context session: this event's distinct id is not the session's + # user, and a session takes the person of its latest event. + return self._enqueue( + msg, + disable_geoip, + context_properties=_context_tag_defaults(), + context_options=_context_get_context_options(), + ) @no_throw() def alias( @@ -2799,6 +2794,7 @@ def alias( timestamp: Optional[Union[datetime, str]] = None, uuid: Optional[str] = None, disable_geoip: Optional[bool] = None, + options: Optional[Dict[str, Any]] = None, ) -> Optional[str]: """ Create an alias between two distinct IDs. @@ -2806,15 +2802,17 @@ def alias( Args: previous_id: The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty. - distinct_id: The new distinct ID to alias to. Falls back to the - context distinct ID; the call is dropped with a warning if - neither is available. + distinct_id: The new distinct ID to alias to. Required - the call is + dropped with a warning if it is missing or empty. The context + distinct ID is never used here. timestamp: The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC. uuid: A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID. disable_geoip: Whether to disable GeoIP for this event. + options: Capture options for this event, sent as given. + ``process_person_profile`` is ``True`` unless this call sets it. Examples: ```python @@ -2833,10 +2831,10 @@ def alias( ) return None - (distinct_id, personless) = get_identity_state(distinct_id) - - if personless: - # No alias target was passed and none is available from context. + # The alias target always comes from the caller: a context id can come + # from a client-controlled request header. + distinct_id = _explicit_distinct_id(distinct_id) + if not distinct_id: self.log.warning( "alias() called without a distinct_id, dropping the $create_alias event" ) @@ -2851,30 +2849,41 @@ def alias( "event": "$create_alias", "distinct_id": previous_id, "uuid": uuid, + "options": _event_options(options), } if get_context_session_id(): msg["properties"]["$session_id"] = str(get_context_session_id()) - return self._enqueue(msg, disable_geoip) + return self._enqueue( + msg, + disable_geoip, + context_properties=_context_tag_defaults(), + context_options=_context_get_context_options(), + ) def capture_exception( self, exception: Optional[ExceptionArg], + *, + level: Optional[str] = None, **kwargs: Unpack[OptionalCaptureArgs], ) -> Optional[str]: """ Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and - span IDs are added as ``$trace_id`` and ``$span_id`` event properties. + span IDs are added as ``$trace_id`` and ``$span_id`` event properties, + unless the event, a context tag or ``super_properties`` sets either one. Args: exception: The exception to capture. + level: The ``$exception_level``, such as ``"warning"`` or ``"fatal"``. + Defaults to ``"error"``. An unknown value counts as unset. distinct_id: The distinct ID of the user. - properties: A dictionary of additional properties. Overriding reserved - exception properties is deprecated and will stop working in the next - major version. + properties: A dictionary of additional properties. Reserved exception + properties, such as ``$exception_list`` and ``$exception_level``, + are ignored. flags: A ``FeatureFlagEvaluations`` snapshot from ``evaluate_flags()``. Attaches those exact flag values to the captured `$exception` event. send_feature_flags: Deprecated. Pass ``flags`` from ``evaluate_flags()`` instead. @@ -2902,18 +2911,104 @@ def capture_exception( try: properties = properties or {} - exc_info = self._exception_info(exception) - if exc_info is None: + # Check if this exception has already been captured + if exception is not None and exception_is_already_captured(exception): + self.log.debug("Exception already captured, skipping") + return None + + if exception is not None: + exc_info = exc_info_from_error(exception) + else: + exc_info = sys.exc_info() + + if exc_info is None or exc_info == (None, None, None): + self.log.warning("No exception information available") + return None + + if exception is None and exception_is_already_captured(exc_info): + self.log.debug("Exception already captured, skipping") return None - properties, all_exceptions_with_trace_and_in_app = ( - self._exception_properties(exc_info, properties, kwargs) + # Format stack trace for cymbal + capture_metadata_input = dict(kwargs).get("_capture_metadata") + capture_metadata = ( + capture_metadata_input + if isinstance(capture_metadata_input, dict) + else {} + ) + mechanism = capture_metadata.get("mechanism") + all_exceptions_with_trace = exceptions_from_error_tuple( + exc_info, mechanism=mechanism if isinstance(mechanism, dict) else None + ) + + # Add in-app property to frames in the exceptions + event = handle_in_app( + { + "exception": { + "values": all_exceptions_with_trace, + }, + }, + in_app_include=self.in_app_modules, + project_root=self.project_root, + ) + all_exceptions_with_trace_and_in_app = event["exception"]["values"] + + caller_properties = properties + properties = { + "$exception_list": all_exceptions_with_trace_and_in_app, + "$exception_level": _exception_level( + capture_metadata.get("level"), level + ), + } + source = capture_metadata.get("source") + if isinstance(source, str) and source: + properties["$exception_source"] = source + properties.update(_without_reserved_exception_properties(caller_properties)) + + context_enabled = get_capture_exception_code_variables_context() + context_mask = get_code_variables_mask_patterns_context() + context_ignore = get_code_variables_ignore_patterns_context() + context_mask_url_credentials = ( + get_code_variables_mask_url_credentials_context() ) + context_detect_secrets = get_code_variables_detect_secrets_context() - self._attach_exception_code_variables( - all_exceptions_with_trace_and_in_app, exc_info + enabled = ( + context_enabled + if context_enabled is not None + else self.capture_exception_code_variables + ) + mask_patterns = ( + context_mask + if context_mask is not None + else self.code_variables_mask_patterns + ) + ignore_patterns = ( + context_ignore + if context_ignore is not None + else self.code_variables_ignore_patterns + ) + mask_url_credentials = ( + context_mask_url_credentials + if context_mask_url_credentials is not None + else self.code_variables_mask_url_credentials + ) + detect_secrets = ( + context_detect_secrets + if context_detect_secrets is not None + else self.code_variables_detect_secrets ) + if enabled: + try_attach_code_variables_to_frames( + all_exceptions_with_trace_and_in_app, + exc_info, + mask_patterns=mask_patterns, + ignore_patterns=ignore_patterns, + mask_url_credentials=mask_url_credentials, + detect_secrets=detect_secrets, + ) + if self.log_captured_exceptions: self.log.exception(exception, extra=kwargs) @@ -2930,6 +3025,8 @@ def capture_exception( flags=flags_snapshot, send_feature_flags=send_feature_flags, disable_geoip=disable_geoip, + options=kwargs.get("options", None), + _capture_trace_context=True, ) # Mark the exception as captured to prevent duplicate captures, @@ -2942,144 +3039,6 @@ def capture_exception( self.log.exception(f"Failed to capture exception: {e}") return None - def _exception_info(self, exception): - # Check if this exception has already been captured - if exception is not None and exception_is_already_captured(exception): - self.log.debug("Exception already captured, skipping") - return None - - if exception is not None: - exc_info = exc_info_from_error(exception) - else: - exc_info = sys.exc_info() - - if exc_info is None or exc_info == (None, None, None): - self.log.warning("No exception information available") - return None - - if exception is None and exception_is_already_captured(exc_info): - self.log.debug("Exception already captured, skipping") - return None - - return exc_info - - def _exception_properties(self, exc_info, properties, kwargs): - # Format stack trace for cymbal - capture_metadata_input = dict(kwargs).get("_capture_metadata") - capture_metadata = ( - capture_metadata_input if isinstance(capture_metadata_input, dict) else {} - ) - mechanism = capture_metadata.get("mechanism") - all_exceptions_with_trace = exceptions_from_error_tuple( - exc_info, mechanism=mechanism if isinstance(mechanism, dict) else None - ) - - # Add in-app property to frames in the exceptions - event = handle_in_app( - { - "exception": { - "values": all_exceptions_with_trace, - }, - }, - in_app_include=self.in_app_modules, - project_root=self.project_root, - ) - all_exceptions_with_trace_and_in_app = event["exception"]["values"] - - reserved_properties = { - "$exception_list", - "$exception_level", - "$exception_source", - "$debug_images", - "$exception_handled", - "$exception_types", - "$exception_values", - "$exception_sources", - "$exception_functions", - "$exception_fingerprint_version", - "$exception_fingerprint_record", - "$exception_issue_id", - "$exception_release", - "$cymbal_errors", - } - reserved_property_overrides = reserved_properties.intersection(properties) - if reserved_property_overrides: - try: - warnings.warn( - "Reserved exception properties passed through " - "`capture_exception(properties=...)` currently override " - "SDK-owned metadata, but this behavior is deprecated and will " - "be removed in the next major version: " - + ", ".join(sorted(reserved_property_overrides)), - DeprecationWarning, - stacklevel=3, - ) - except DeprecationWarning: - # capture_exception must not drop an event when applications - # promote deprecation warnings to errors. - pass - - caller_properties = properties - properties = { - **_get_current_otel_span_properties(), - "$exception_list": all_exceptions_with_trace_and_in_app, - "$exception_level": _normalize_exception_level( - capture_metadata.get("level") - ) - or "error", - } - source = capture_metadata.get("source") - if isinstance(source, str) and source: - properties["$exception_source"] = source - properties.update(caller_properties) - - return properties, all_exceptions_with_trace_and_in_app - - def _attach_exception_code_variables( - self, all_exceptions_with_trace_and_in_app, exc_info - ): - context_enabled = get_capture_exception_code_variables_context() - context_mask = get_code_variables_mask_patterns_context() - context_ignore = get_code_variables_ignore_patterns_context() - context_mask_url_credentials = get_code_variables_mask_url_credentials_context() - context_detect_secrets = get_code_variables_detect_secrets_context() - - enabled = ( - context_enabled - if context_enabled is not None - else self.capture_exception_code_variables - ) - mask_patterns = ( - context_mask - if context_mask is not None - else self.code_variables_mask_patterns - ) - ignore_patterns = ( - context_ignore - if context_ignore is not None - else self.code_variables_ignore_patterns - ) - mask_url_credentials = ( - context_mask_url_credentials - if context_mask_url_credentials is not None - else self.code_variables_mask_url_credentials - ) - detect_secrets = ( - context_detect_secrets - if context_detect_secrets is not None - else self.code_variables_detect_secrets - ) - - if enabled: - try_attach_code_variables_to_frames( - all_exceptions_with_trace_and_in_app, - exc_info, - mask_patterns=mask_patterns, - ignore_patterns=ignore_patterns, - mask_url_credentials=mask_url_credentials, - detect_secrets=detect_secrets, - ) - @classmethod def _reinit_client_registry_after_fork(cls): """Replace the inherited registry lock once in each forked child.""" @@ -3179,9 +3138,6 @@ def _reinit_after_fork(self): reset_sessions() # Start child threads only after replacing every lock they can touch. - self._restart_flag_poller_after_fork(terminal_requested) - - def _restart_flag_poller_after_fork(self, terminal_requested): if terminal_requested: self.poller = None elif self.enable_local_evaluation: @@ -3196,17 +3152,27 @@ def _restart_flag_poller_after_fork(self, terminal_requested): def _normalize_event_uuid(self, msg): # type: (...) -> None """Ensure `msg["uuid"]` is a valid uuid string, generating one if missing or invalid.""" - if "uuid" in msg: - uuid = msg.pop("uuid") - if uuid is not None: - try: - msg["uuid"] = _stringify_event_uuid(uuid) - except ValueError as e: - self.log.error("%s Falling back to a generated UUID.", e) + # Always send a uuid, so we can always return one + msg["uuid"] = _resolve_event_uuid(msg.pop("uuid", None)) - if "uuid" not in msg: - # Always send a uuid, so we can always return one - msg["uuid"] = stringify_id(uuid4()) + def _report_capture_failure( + self, error: Exception, batch: list[dict], endpoint: str + ) -> None: + """Hand a failed sync-mode send to `on_error`, like the queued path does. + + Without a handler, or when the failed capture ran inside `on_error`, + log one aggregate line instead, so the loss stays visible without recursion. + """ + if not self.on_error or getattr(_on_error_state, "active", False): + self.log.error(_capture_loss_message(error, len(batch), endpoint)) + return + _on_error_state.active = True + try: + self.on_error(error, batch) + except Exception as callback_error: + self.log.error("on_error handler failed: %s", callback_error) + finally: + _on_error_state.active = False def _enqueue( self, @@ -3214,6 +3180,12 @@ def _enqueue( disable_geoip, lane=None, property_allowlist=None, + context_properties=None, + context_options=None, + personless=False, + system_properties=None, + flag_properties=None, + trace_properties=None, pinned_properties=None, before_send_drops=None, ): @@ -3226,30 +3198,6 @@ def _enqueue( if self.disabled: return None - self._normalize_event_timestamp(msg) - - self._normalize_event_uuid(msg) - - self._enrich_event_properties( - msg, disable_geoip, property_allowlist, pinned_properties - ) - - msg = clean(msg) - - msg = self._run_before_send(msg, before_send_drops) - if msg is None: - return None - - # Re-normalized after before_send, which may have replaced or removed - # msg["uuid"], so the returned uuid always matches the wire event. - self._normalize_event_uuid(msg) - sent_uuid = msg["uuid"] - - self.log.debug("queueing: %s", msg) - - return self._submit_event(msg, lane, sent_uuid) - - def _normalize_event_timestamp(self, msg): timestamp = msg["timestamp"] if timestamp is None: timestamp = datetime.now(tz=timezone.utc) @@ -3259,57 +3207,54 @@ def _normalize_event_timestamp(self, msg): msg["timestamp"] = _normalize_timestamp(timestamp) except ValueError: self.log.warning( - "Invalid timestamp %r. Falling back to the current UTC time.", timestamp + "Invalid timestamp; it must be a datetime or an ISO 8601 string. " + "Falling back to the current UTC time." ) - msg["timestamp"] = datetime.now(tz=timezone.utc).isoformat() + msg["timestamp"] = _rfc3339_timestamp(datetime.now(tz=timezone.utc)) + + self._normalize_event_uuid(msg) - def _enrich_event_properties( - self, msg, disable_geoip, property_allowlist, pinned_properties - ): if not msg.get("properties"): msg["properties"] = {} - msg["properties"]["$lib"] = self._library_id - msg["properties"]["$lib_version"] = self._library_version - if disable_geoip is None: - disable_geoip = self.disable_geoip + msg["options"] = msg.get("options") or {} - if disable_geoip: - msg["properties"]["$geoip_disable"] = True + _fill_event_defaults( + msg, + _build_event_defaults( + super_properties=self.super_properties, + super_options=self.super_options, + release_id=self._release_id, + context_properties=context_properties, + context_options=context_options, + personless=personless, + property_allowlist=property_allowlist, + is_server=self.is_server, + disable_geoip=self.disable_geoip, + call_disable_geoip=disable_geoip, + system_properties=system_properties, + flag_properties=flag_properties, + trace_properties=trace_properties, + library_id=self._library_id, + library_version=self._library_version, + pinned_properties=pinned_properties, + ), + ) - if self.super_properties: - msg["properties"] = {**msg["properties"], **self.super_properties} + # Applied after every enrichment step (system context, $lib/$lib_version, + # filled defaults), so the final event shape is exactly the allowlist + # regardless of where a property came from. + if property_allowlist is not None: + msg["properties"] = { + k: v for k, v in msg["properties"].items() if k in property_allowlist + } - # Set after the super_properties merge so an explicit `$release_id` from - # the caller's properties or the super properties wins over the env var. - if self._release_id is not None: - msg["properties"].setdefault("$release_id", self._release_id) + msg["distinct_id"] = stringify_id(msg.get("distinct_id", None)) - # Set after the super_properties merge so this SDK's server classification - # can't be silently overridden by a user-provided super property. - if self.is_server: - msg["properties"]["$is_server"] = True + msg = clean(msg) - self._filter_event_properties(msg, property_allowlist, pinned_properties) - - msg["distinct_id"] = stringify_id(msg.get("distinct_id", None)) - - def _filter_event_properties(self, msg, property_allowlist, pinned_properties): - # Applied after every enrichment step (system context, context tags, super - # properties, $lib/$lib_version) so the final event shape is exactly the - # allowlist regardless of where a property came from. - # After every enrichment step, so a super property never changes or adds - # config version 2 flag attribution. - if pinned_properties is not None: - msg["properties"] = pinned_properties.apply(msg["properties"]) - - if property_allowlist is not None: - msg["properties"] = { - k: v for k, v in msg["properties"].items() if k in property_allowlist - } - - def _run_before_send(self, msg, before_send_drops): if self.before_send: + event_name = msg.get("event") try: modified_msg = self.before_send(msg) if modified_msg is None: @@ -3318,15 +3263,25 @@ def _run_before_send(self, msg, before_send_drops): before_send_drops.append(msg["event"]) return None if not isinstance(modified_msg, dict): - raise TypeError("before_send must return a dict or None") + _log_before_send_bad_return(self.log, event_name, modified_msg) + return None msg = clean(modified_msg) except Exception as e: - self.log.exception(f"Error in before_send callback: {e}") + _log_before_send_error(self.log, event_name, e) return None - return msg + # Re-normalized after before_send, which may have replaced or removed + # msg["uuid"], so the returned uuid always matches the wire event. + self._normalize_event_uuid(msg) + sent_uuid = msg["uuid"] + + if _drop_invalid_event_name(self.log, msg): + return None + if _drop_invalid_distinct_id(self.log, msg): + return None + + self.log.debug("queueing %s on the %s lane", msg["event"], lane.name) - def _submit_event(self, msg, lane, sent_uuid): # if send is False, return msg as if it was successfully queued, unless # shutdown has already closed this lane's admission. if not self.send: @@ -3342,7 +3297,48 @@ def _submit_event(self, msg, lane, sent_uuid): if self.sync_mode: self.log.debug("enqueued with blocking %s.", msg["event"]) - if lane.run_sync_if_open(lambda: self._send_sync(msg, lane)): + try: + event_size = len( + json.dumps(msg, cls=_DatetimeSerializer, allow_nan=False).encode() + ) + except Exception: + self.log.error("Unable to serialize event for sizing, dropping.") + return None + if event_size > lane.max_msg_size: + # Log only name and size: AI events may carry unredacted + # multimodal payloads that must not leak into logs. + self.log.error( + "Event %s (%d bytes) exceeds the %dKiB limit for %s, dropping.", + msg["event"], + event_size, + lane.max_msg_size // 1024, + lane.endpoint, + ) + return None + + def send_sync() -> None: + # Sync mode bypasses the lane's queue but keeps its wire config, + # so AI events still post to the AI endpoint. + _send_v1_batch( + self.api_key, + self.host, + [msg], + compression=lane.capture_compression, + timeout=lane.timeout, + max_retries=self.max_retries, + historical_migration=self.historical_migration, + sdk_info=self._sdk_info, + path=lane.endpoint, + ) + + try: + admitted = lane.run_sync_if_open(send_sync) + except Exception as e: + self._report_capture_failure(e, [msg], lane.endpoint) + if self.debug: + raise + return None + if admitted: return sent_uuid self.log.warning( "%s lane received event %s after shutdown, dropping it", @@ -3377,34 +3373,6 @@ def _submit_event(self, msg, lane, sent_uuid): ) return None - def _send_sync(self, msg, lane) -> None: - # Sync mode bypasses the lane's queue but keeps its wire config: - # the AI lane is pinned to v0, so its events post to the AI - # endpoint regardless of `capture_mode`. - if lane.capture_mode == CaptureMode.V1: - _send_v1_batch( - self.api_key, - self.host, - [msg], - compression=self.capture_compression, - timeout=self.timeout, - max_retries=self.max_retries, - historical_migration=self.historical_migration, - sdk_info=self._sdk_info, - ) - return - - batch_post( - self.api_key, - self.host, - gzip=self.gzip, - timeout=self.timeout, - batch=[msg], - historical_migration=self.historical_migration, - path=lane.endpoint, - **self._request_identity_kwargs(), - ) - @property def metrics(self) -> PostHogMetrics: """ @@ -3453,33 +3421,30 @@ def _traces_pipeline(self) -> Optional[PostHogTraces]: # Re-checked under the lock, which shutdown takes before it # reads the pipeline, so neither can miss the other. if self._traces is None and not self._shutdown_requested: - self._initialize_traces_pipeline() + try: + config = resolve_traces_config( + self._traces_config, host_resource_attributes() + ) + drops = DropLog(config.flush_interval) + self._traces = PostHogTraces( + self, + config, + self._tracing_context, + self._active_span_var, + SpanExporter(self, config, drops), + drops, + ) + # Sync mode has no exit hook for events; spans still + # queue for the timer, so they need their own. + if self.sync_mode and self.send: + atexit.register(self._atexit_spans) + except Exception: + # Off rather than defaults: defaults would drop a + # before_span_send hook and export unscrubbed spans. + self.log.exception("Error initializing traces; tracing is off") + self._traces_config = False return self._traces - def _initialize_traces_pipeline(self) -> None: - try: - config = resolve_traces_config( - self._traces_config, host_resource_attributes() - ) - drops = DropLog(config.flush_interval) - self._traces = PostHogTraces( - self, - config, - self._tracing_context, - self._active_span_var, - SpanExporter(self, config, drops), - drops, - ) - # Sync mode has no exit hook for events; spans still - # queue for the timer, so they need their own. - if self.sync_mode and self.send: - atexit.register(self._atexit_spans) - except Exception: - # Off rather than defaults: defaults would drop a - # before_span_send hook and export unscrubbed spans. - self.log.exception("Error initializing traces; tracing is off") - self._traces_config = False - def _tracing_context(self) -> Dict[str, Optional[str]]: # The request context's identity, which the Django middleware fills # from the X-POSTHOG-* headers: the span's person/session join keys. @@ -3498,12 +3463,17 @@ def start_span( """ Start a span for distributed tracing. Alpha. + The span API is experimental and can change in a minor release. Spans + already sent are kept; the SDK API isn't frozen yet. + 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. + code never branches. At ``max_live_spans`` open spans, the SDK first + evicts spans open longer than ``max_span_age`` seconds, which are never + exported. If it is still at the limit, the returned span isn't recorded. Args: name: A low-cardinality operation name, e.g. ``GET /users/:id``. @@ -3514,10 +3484,19 @@ def start_span( parent: 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. + span to continue a trace across a fork. The active span is + tracked with ``contextvars``, so it carries across ``await``. + Threads don't reliably inherit it, so pass ``parent=span`` in + a thread or a ``ThreadPoolExecutor`` task. A malformed + ``traceparent`` starts a new trace and doesn't raise. A + continued trace propagates the sampled flag it received. + PostHog doesn't sample, so the span is exported whichever way + the flag is set. tracestate: The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated. start_time: A ``datetime`` or epoch seconds, to backdate the span. + PostHog clamps a start time more than 24 hours old to the + receive time. Examples: ```python @@ -3619,7 +3598,15 @@ def flush(self, timeout_seconds: Optional[float] = 10) -> None: if include_metrics_autocapture else None ) - deadline = self._flush_lanes(timeout_seconds) + deadline: Optional[float] = None + with self._drain_lanes_together(): + if timeout_seconds is None: + for lane in self._lanes: + lane.flush(None) + else: + deadline = time.monotonic() + timeout_seconds + for lane in self._lanes: + lane.flush(max(0.0, deadline - time.monotonic())) if metrics_flush is not None: metrics_flush( None if deadline is None else max(0.0, deadline - time.monotonic()) @@ -3632,17 +3619,6 @@ def flush(self, timeout_seconds: Optional[float] = 10) -> None: self.log.exception("error flushing queue: %s", e) return - def _flush_lanes(self, timeout_seconds): - deadline: Optional[float] = None - if timeout_seconds is None: - for lane in self._lanes: - lane.flush(None) - else: - deadline = time.monotonic() + timeout_seconds - for lane in self._lanes: - lane.flush(max(0.0, deadline - time.monotonic())) - return deadline - def _start_metrics_autocapture_flush( self, ) -> Optional[Callable[[Optional[float]], None]]: @@ -3791,7 +3767,36 @@ def _run_lifecycle_cleanup( self.log.exception(log_message) errors.append(error) + @contextmanager + def _drain_lanes_together(self): + """Signal every lane to drain before waiting on any of them. + + Lanes then drain in parallel under one budget. Otherwise a lane keeps + batching on its normal cadence while the client waits on the lane before it. + """ + signals: list[_DrainSignal] = [] + try: + for lane in self._lanes: + signal = lane._drain_signal + signal.request() + signals.append(signal) + yield + finally: + for signal in signals: + signal.complete() + def _flush_or_discard_queues(self, errors: list[Exception]) -> None: + try: + with self._drain_lanes_together(): + self._flush_or_discard_each_lane(errors) + return + except Exception as error: + self.log.exception("Failed to signal lane drains during lifecycle cleanup") + errors.append(error) + # Each lane's flush signals its own drain, so lanes still drain one by one. + self._flush_or_discard_each_lane(errors) + + def _flush_or_discard_each_lane(self, errors: list[Exception]) -> None: for lane in self._lanes: try: if any(consumer.is_alive() for consumer in lane.consumers): @@ -3837,9 +3842,6 @@ def _join_once( # means every worker cleanup step was attempted once. self._workers_joined = True - self._close_lifecycle_resources(errors) - - def _close_lifecycle_resources(self, errors: list[Exception]) -> None: if not self._join_cleanup_complete: if self.poller: self._run_lifecycle_cleanup( @@ -3938,7 +3940,15 @@ def _shutdown_once(self, errors: list[Exception]) -> None: def _run_lifecycle(self, require_shutdown: bool = False) -> None: while True: with self._lifecycle_condition: - if self._lifecycle_has_completed(require_shutdown): + if require_shutdown and self._shutdown_complete: + if self.debug and self._lifecycle_cleanup_failed: + raise RuntimeError("client lifecycle cleanup failed") + return + if not require_shutdown and ( + self._join_cleanup_complete or self._shutdown_complete + ): + if self.debug and self._lifecycle_cleanup_failed: + raise RuntimeError("client lifecycle cleanup failed") return if self._lifecycle_owner is not None: if self._is_lifecycle_callback_thread() or ( @@ -3950,54 +3960,35 @@ def _run_lifecycle(self, require_shutdown: bool = False) -> None: self._lifecycle_owner = threading.current_thread() try: - self._finish_lifecycle() - return + errors: list[Exception] = [] + while True: + with self._lifecycle_lock: + run_shutdown = self._shutdown_requested + + if run_shutdown: + self._shutdown_once(errors) + else: + self._join_once(errors) + + with self._lifecycle_condition: + if ( + self._shutdown_requested + and not self._shutdown_complete + and not run_shutdown + ): + continue + if errors: + self._lifecycle_cleanup_failed = True + raise errors[0] + self._lifecycle_owner = None + self._lifecycle_condition.notify_all() + return except BaseException: with self._lifecycle_condition: self._lifecycle_owner = None self._lifecycle_condition.notify_all() raise - def _lifecycle_has_completed(self, require_shutdown: bool) -> bool: - if require_shutdown and self._shutdown_complete: - self._raise_lifecycle_failure() - return True - if not require_shutdown and ( - self._join_cleanup_complete or self._shutdown_complete - ): - self._raise_lifecycle_failure() - return True - return False - - def _raise_lifecycle_failure(self) -> None: - if self.debug and self._lifecycle_cleanup_failed: - raise RuntimeError("client lifecycle cleanup failed") - - def _finish_lifecycle(self) -> None: - errors: list[Exception] = [] - while True: - with self._lifecycle_lock: - run_shutdown = self._shutdown_requested - - if run_shutdown: - self._shutdown_once(errors) - else: - self._join_once(errors) - - with self._lifecycle_condition: - if ( - self._shutdown_requested - and not self._shutdown_complete - and not run_shutdown - ): - continue - if errors: - self._lifecycle_cleanup_failed = True - raise errors[0] - self._lifecycle_owner = None - self._lifecycle_condition.notify_all() - return - @no_throw() def _atexit(self) -> None: """Make a bounded delivery attempt, then stop daemon workers.""" @@ -4095,6 +4086,8 @@ def shutdown(self) -> None: flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. + A script that exits without calling ``shutdown()`` gets only a brief + best-effort span flush, so don't rely on it. 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 @@ -4309,7 +4302,18 @@ def _local_evaluation_snapshot(self) -> _LocalEvaluationSnapshot: } def _load_feature_flags(self): - should_fetch = self._should_fetch_flag_definitions() + should_fetch = True + if self._flag_definition_cache_provider: + try: + should_fetch = self._resolve_flag_definition_cache_provider_result( + self._flag_definition_cache_provider.should_fetch_flag_definitions() + ) + except Exception as e: + self.log.error( + f"[FEATURE FLAGS] Cache provider should_fetch error: {e}" + ) + # Fail-safe: fetch from API if cache provider errors + should_fetch = True # If not fetching, try to get from cache if not should_fetch and self._flag_definition_cache_provider: @@ -4343,22 +4347,6 @@ def _load_feature_flags(self): if should_fetch: self._fetch_feature_flags_from_api() - def _should_fetch_flag_definitions(self): - should_fetch = True - if self._flag_definition_cache_provider: - try: - should_fetch = self._resolve_flag_definition_cache_provider_result( - self._flag_definition_cache_provider.should_fetch_flag_definitions() - ) - except Exception as e: - self.log.error( - f"[FEATURE FLAGS] Cache provider should_fetch error: {e}" - ) - # Fail-safe: fetch from API if cache provider errors - should_fetch = True - - return should_fetch - def _fetch_feature_flags_from_api(self): """Fetch feature flags from the PostHog API.""" personal_api_key = self.personal_api_key @@ -4376,194 +4364,169 @@ def _fetch_feature_flags_from_api(self): cache_data_to_store: Optional[FlagDefinitionCacheData] = None old_fingerprint: Optional[str] = None try: - response, fingerprint = self._request_flag_definitions( - personal_api_key, request_etag - ) - published, old_fingerprint, cache_data_to_store = ( - self._publish_flag_definitions_response( - response, fingerprint, fetch_generation, request_etag - ) - ) - if not published: - return - self._warn_unresolvable_flags() - self._store_flag_definitions_if_current( - cache_data_to_store, fetch_generation + response = get( + personal_api_key, + f"/flags/definitions?token={self.api_key}&send_cohorts", + self.host, + timeout=10, + etag=request_etag, ) - except APIError as e: - with self._flag_definition_publication_lock: - if ( - fetch_generation > self._flag_definition_published_generation - and e.status in (401, 402) - ): - old_fingerprint = self._flag_definition_fingerprint - debug_error = self._handle_flag_definition_api_error( - e, fetch_generation - ) - if debug_error is not None: - raise debug_error - except Exception as e: - self.log.warning( - "[FEATURE FLAGS] Fetching feature flags failed with following error. We will retry in %s seconds." - % self.poll_interval + # Canonical serialization can be expensive; do it before publication. + fingerprint = ( + self._hash_flag_definitions(response.data) + if response.data is not None and not response.not_modified + else None ) - self.log.warning(e) - finally: - # Legacy readers ignore snapshot metadata. Cleanup is best effort and - # must not hold the publication lock, including when debug raises. - if isinstance(self.flag_cache, RedisFlagCache): - self.flag_cache._invalidate_snapshot(old_fingerprint) - self._last_feature_flag_poll = datetime.now(tz=timezone.utc) + with self._flag_definition_publication_lock: + if fetch_generation <= self._flag_definition_published_generation: + self.log.debug( + "[FEATURE FLAGS] Ignoring stale flag definition response" + ) + self._last_feature_flag_poll = datetime.now(tz=timezone.utc) + return - def _request_flag_definitions(self, personal_api_key, request_etag): - request_get = _get_with_identity if self._request_identity_kwargs() else get - response = request_get( - personal_api_key, - f"/flags/definitions?token={self.api_key}&send_cohorts", - self.host, - timeout=10, - etag=request_etag, - **self._request_identity_kwargs(), - ) + # A 304 is valid only for the ETag used by this request. Another + # overlapping response may already have installed newer definitions. + if response.not_modified: + if self._flags_etag != request_etag: + self.log.debug( + "[FEATURE FLAGS] Ignoring stale 304 flag definition response" + ) + self._last_feature_flag_poll = datetime.now(tz=timezone.utc) + return - # Canonical serialization can be expensive; do it before publication. - fingerprint = ( - self._hash_flag_definitions(response.data) - if response.data is not None and not response.not_modified - else None - ) + self._flags_etag = response.etag + self._flag_definition_published_generation = fetch_generation + self._flag_definition_cache_generation = fetch_generation + self.log.debug( + "[FEATURE FLAGS] Flags not modified (304), using cached data" + ) + self._last_feature_flag_poll = datetime.now(tz=timezone.utc) + return - return response, fingerprint + if response.data is None: + self.log.error( + "[FEATURE FLAGS] Unexpected empty response data in non-304 response" + ) + return - def _publish_flag_definitions_response( - self, response, fingerprint, fetch_generation, request_etag - ): - cache_data_to_store = None - with self._flag_definition_publication_lock: - if fetch_generation <= self._flag_definition_published_generation: - self.log.debug( - "[FEATURE FLAGS] Ignoring stale flag definition response" + old_fingerprint = self._update_flag_state( + response.data, _fingerprint=fingerprint ) - self._last_feature_flag_poll = datetime.now(tz=timezone.utc) - return False, None, None - # A 304 is valid only for the ETag used by this request. Another - # overlapping response may already have installed newer definitions. - if response.not_modified: - if self._flags_etag != request_etag: - self.log.debug( - "[FEATURE FLAGS] Ignoring stale 304 flag definition response" - ) - self._last_feature_flag_poll = datetime.now(tz=timezone.utc) - return False, None, None + if self._flag_definition_cache_provider: + cache_data_to_store = { + "flags": self.feature_flags or [], + "group_type_mapping": self.group_type_mapping or {}, + "cohorts": self.cohorts or {}, + "minimal_flag_called_events": self._minimal_flag_called_events, + "property_matching_version": self._property_matching_version, + } + # Publish the ETag only after its matching flag state is installed. self._flags_etag = response.etag self._flag_definition_published_generation = fetch_generation self._flag_definition_cache_generation = fetch_generation - self.log.debug( - "[FEATURE FLAGS] Flags not modified (304), using cached data" - ) - self._last_feature_flag_poll = datetime.now(tz=timezone.utc) - return False, None, None - - if response.data is None: - self.log.error( - "[FEATURE FLAGS] Unexpected empty response data in non-304 response" - ) - return False, None, None - old_fingerprint = self._update_flag_state( - response.data, _fingerprint=fingerprint - ) + self._warn_unresolvable_flags() - if self._flag_definition_cache_provider: - cache_data_to_store = { - "flags": self.feature_flags or [], - "group_type_mapping": self.group_type_mapping or {}, - "cohorts": self.cohorts or {}, - "minimal_flag_called_events": self._minimal_flag_called_events, - "property_matching_version": self._property_matching_version, - } + if cache_data_to_store and self._flag_definition_cache_provider: + # Keep provider I/O out of the publication lock. The separate lock + # preserves cache write order without delaying newer API fetches or + # in-memory publication. + with self._flag_definition_cache_write_lock: + with self._flag_definition_publication_lock: + should_store = ( + fetch_generation == self._flag_definition_cache_generation + ) + if should_store: + try: + self._resolve_flag_definition_cache_provider_result( + self._flag_definition_cache_provider.on_flag_definitions_received( + cache_data_to_store + ) + ) + except Exception as e: + self.log.error( + f"[FEATURE FLAGS] Cache provider store error: {e}" + ) + # Flags are already in memory, so continue normally - # Publish the ETag only after its matching flag state is installed. - self._flags_etag = response.etag - self._flag_definition_published_generation = fetch_generation - self._flag_definition_cache_generation = fetch_generation - - return True, old_fingerprint, cache_data_to_store - - def _store_flag_definitions_if_current(self, cache_data_to_store, fetch_generation): - if cache_data_to_store and self._flag_definition_cache_provider: - # Keep provider I/O out of the publication lock. The separate lock - # preserves cache write order without delaying newer API fetches or - # in-memory publication. - with self._flag_definition_cache_write_lock: - with self._flag_definition_publication_lock: - should_store = ( - fetch_generation == self._flag_definition_cache_generation + except APIError as e: + with self._flag_definition_publication_lock: + if fetch_generation <= self._flag_definition_published_generation: + self.log.debug("[FEATURE FLAGS] Ignoring stale API error response") + elif e.status == 401: + detail = ( + f"Error loading feature flags: {e.message}. " + "Please verify both your project_api_key and secret_key. " + "More information: https://posthog.com/docs/api/overview" ) - if should_store: - try: - self._resolve_flag_definition_cache_provider_result( - self._flag_definition_cache_provider.on_flag_definitions_received( - cache_data_to_store - ) + self.log.error("[FEATURE FLAGS] %s", detail) + self.feature_flags = [] + self.group_type_mapping = {} + self.cohorts = {} + self._property_matching_version = 1 + old_fingerprint = self._flag_definition_fingerprint + self._flag_definition_fingerprint = "" + self._flags_etag = None + self._flag_definition_published_generation = fetch_generation + self._flag_definition_cache_generation = fetch_generation + + if self.flag_cache: + self.flag_definition_version += 1 + self.flag_cache._advance_generation( + self.flag_definition_version, + self._flag_definition_fingerprint, ) - except Exception as e: - self.log.error( - f"[FEATURE FLAGS] Cache provider store error: {e}" + + if self.debug: + raise APIError(status=401, message=detail) + elif e.status == 402: + self.log.warning( + "[FEATURE FLAGS] PostHog feature flags quota limited, resetting feature flag data. Learn more about billing limits at https://posthog.com/docs/billing/limits-alerts" + ) + # Reset all feature flag data when quota limited + self.feature_flags = [] + self.group_type_mapping = {} + self.cohorts = {} + self._property_matching_version = 1 + old_fingerprint = self._flag_definition_fingerprint + self._flag_definition_fingerprint = "" + self._flags_etag = None + self._flag_definition_published_generation = fetch_generation + self._flag_definition_cache_generation = fetch_generation + + # Invalidate results without waiting for external cache I/O. + if self.flag_cache: + self.flag_definition_version += 1 + self.flag_cache._advance_generation( + self.flag_definition_version, + self._flag_definition_fingerprint, ) - # Flags are already in memory, so continue normally - - def _handle_flag_definition_api_error(self, e, fetch_generation): - debug_error = None - if fetch_generation <= self._flag_definition_published_generation: - self.log.debug("[FEATURE FLAGS] Ignoring stale API error response") - elif e.status == 401: - detail = ( - f"Error loading feature flags: {e.message}. " - "Please verify both your project_api_key and secret_key. " - "More information: https://posthog.com/docs/api/overview" - ) - self.log.error("[FEATURE FLAGS] %s", detail) - self._clear_flag_definitions_after_api_error(fetch_generation) - if self.debug: - debug_error = APIError(status=401, message=detail) - elif e.status == 402: + if self.debug: + raise APIError( + status=402, + message="PostHog feature flags quota limited", + ) + else: + self.log.error(f"[FEATURE FLAGS] Error loading feature flags: {e}") + except Exception as e: self.log.warning( - "[FEATURE FLAGS] PostHog feature flags quota limited, resetting feature flag data. Learn more about billing limits at https://posthog.com/docs/billing/limits-alerts" + "[FEATURE FLAGS] Fetching feature flags failed with following error. We will retry in %s seconds." + % self.poll_interval ) - # Reset all feature flag data when quota limited - self._clear_flag_definitions_after_api_error(fetch_generation) - - if self.debug: - debug_error = APIError( - status=402, - message="PostHog feature flags quota limited", - ) - else: - self.log.error(f"[FEATURE FLAGS] Error loading feature flags: {e}") - return debug_error - - def _clear_flag_definitions_after_api_error(self, fetch_generation): - self.feature_flags = [] - self.group_type_mapping = {} - self.cohorts = {} - self._property_matching_version = 1 - self._flag_definition_fingerprint = "" - self._flags_etag = None - self._flag_definition_published_generation = fetch_generation - self._flag_definition_cache_generation = fetch_generation + self.log.warning(e) + finally: + # Legacy readers ignore snapshot metadata. Cleanup is best effort and + # must not hold the publication lock, including when debug raises. + if isinstance(self.flag_cache, RedisFlagCache): + self.flag_cache._invalidate_snapshot(old_fingerprint) - if self.flag_cache: - self.flag_definition_version += 1 - self.flag_cache._advance_generation( - self.flag_definition_version, - self._flag_definition_fingerprint, - ) + self._last_feature_flag_poll = datetime.now(tz=timezone.utc) def load_feature_flags(self): """ @@ -4621,6 +4584,8 @@ def _compute_flag_locally( if _definition_snapshot is not None else self._local_evaluation_snapshot() ) + flags_by_key = snapshot["flags_by_key"] + property_matching_version = snapshot.get("property_matching_version", 1) groups = groups or {} person_properties = person_properties or {} group_properties = group_properties or {} @@ -4639,138 +4604,89 @@ def _compute_flag_locally( flag_filters = feature_flag.get("filters") or {} aggregation_group_type_index = flag_filters.get("aggregation_group_type_index") + group_type_mapping = snapshot["group_type_mapping"] if aggregation_group_type_index is not None: - return self._compute_group_flag_locally( + group_name = group_type_mapping.get(str(aggregation_group_type_index)) + + if not group_name: + self.log.warning( + f"[FEATURE FLAGS] Unknown group type index {aggregation_group_type_index} for feature flag {feature_flag['key']}" + ) + # failover to `/flags` + raise InconclusiveMatchError( + "Flag has unknown group type index", + reason=UnresolvedFlagReason.UNSUPPORTED_DEFINITION, + ) + + if group_name not in groups: + # Group flags are never enabled in `groups` aren't passed in + # don't failover to `/flags`, since response will be the same + if warn_on_unknown_groups: + self.log.warning( + f"[FEATURE FLAGS] Can't compute group feature flag: {feature_flag['key']} without group names passed in" + ) + else: + self.log.debug( + f"[FEATURE FLAGS] Can't compute group feature flag: {feature_flag['key']} without group names passed in" + ) + return False + + if group_name not in group_properties: + raise InconclusiveMatchError( + f"Flag has no group properties for group '{group_name}'", + reason=UnresolvedFlagReason.MISSING_CONTEXT, + ) + focused_group_properties = group_properties[group_name] + group_key = groups[group_name] + return match_feature_flag_properties( feature_flag, - groups, - group_properties, - warn_on_unknown_groups, - device_id, - snapshot, - evaluation_cache, - aggregation_group_type_index, + group_key, + focused_group_properties, + cohort_properties=snapshot["cohorts"], + flags_by_key=flags_by_key, + property_matching_version=property_matching_version, + evaluation_cache=evaluation_cache, + device_id=device_id, + bucketing_value=group_key, + group_type_mapping=group_type_mapping, + groups=groups, + group_properties=group_properties, ) else: - return self._compute_person_flag_locally( + try: + bucketing_value = resolve_bucketing_value( + feature_flag, distinct_id, device_id + ) + except InconclusiveMatchError as e: + # No condition is checked without a bucketing value, so a cause in + # the definition also applies and outranks missing_context. + e.reason = ( + _get_definition_unresolved_reason( + feature_flag, + flags_by_key, + snapshot["cohorts"], + group_type_mapping, + ) + or e.reason + ) + raise + return match_feature_flag_properties( feature_flag, distinct_id, person_properties, - device_id, - snapshot, - evaluation_cache, - groups, - group_properties, + cohort_properties=snapshot["cohorts"], + flags_by_key=flags_by_key, + property_matching_version=property_matching_version, + evaluation_cache=evaluation_cache, + device_id=device_id, + bucketing_value=bucketing_value, + group_type_mapping=group_type_mapping, + groups=groups, + group_properties=group_properties, ) - def _compute_group_flag_locally( - self, - feature_flag, - groups, - group_properties, - warn_on_unknown_groups, - device_id, - snapshot, - evaluation_cache, - aggregation_group_type_index, - ) -> FlagValue: - group_type_mapping = snapshot["group_type_mapping"] - flags_by_key = snapshot["flags_by_key"] - property_matching_version = snapshot.get("property_matching_version", 1) - group_name = group_type_mapping.get(str(aggregation_group_type_index)) - - if not group_name: - self.log.warning( - f"[FEATURE FLAGS] Unknown group type index {aggregation_group_type_index} for feature flag {feature_flag['key']}" - ) - # failover to `/flags` - raise InconclusiveMatchError( - "Flag has unknown group type index", - reason=UnresolvedFlagReason.UNSUPPORTED_DEFINITION, - ) - - if group_name not in groups: - # Group flags are never enabled in `groups` aren't passed in - # don't failover to `/flags`, since response will be the same - if warn_on_unknown_groups: - self.log.warning( - f"[FEATURE FLAGS] Can't compute group feature flag: {feature_flag['key']} without group names passed in" - ) - else: - self.log.debug( - f"[FEATURE FLAGS] Can't compute group feature flag: {feature_flag['key']} without group names passed in" - ) - return False - - if group_name not in group_properties: - raise InconclusiveMatchError( - f"Flag has no group properties for group '{group_name}'", - reason=UnresolvedFlagReason.MISSING_CONTEXT, - ) - focused_group_properties = group_properties[group_name] - group_key = groups[group_name] - return match_feature_flag_properties( - feature_flag, - group_key, - focused_group_properties, - cohort_properties=snapshot["cohorts"], - flags_by_key=flags_by_key, - property_matching_version=property_matching_version, - evaluation_cache=evaluation_cache, - device_id=device_id, - bucketing_value=group_key, - group_type_mapping=group_type_mapping, - groups=groups, - group_properties=group_properties, - ) - - def _compute_person_flag_locally( - self, - feature_flag, - distinct_id, - person_properties, - device_id, - snapshot, - evaluation_cache, - groups, - group_properties, - ) -> FlagValue: - group_type_mapping = snapshot["group_type_mapping"] - flags_by_key = snapshot["flags_by_key"] - property_matching_version = snapshot.get("property_matching_version", 1) - try: - bucketing_value = resolve_bucketing_value( - feature_flag, distinct_id, device_id - ) - except InconclusiveMatchError as e: - # No condition is checked without a bucketing value, so a cause in - # the definition also applies and outranks missing_context. - e.reason = ( - _get_definition_unresolved_reason( - feature_flag, - flags_by_key, - snapshot["cohorts"], - group_type_mapping, - ) - or e.reason - ) - raise - return match_feature_flag_properties( - feature_flag, - distinct_id, - person_properties, - cohort_properties=snapshot["cohorts"], - flags_by_key=flags_by_key, - property_matching_version=property_matching_version, - evaluation_cache=evaluation_cache, - device_id=device_id, - bucketing_value=bucketing_value, - group_type_mapping=group_type_mapping, - groups=groups, - group_properties=group_properties, - ) - - def feature_enabled( + def feature_enabled( self, key: str, distinct_id: ID_TYPES, @@ -4874,33 +4790,20 @@ def _get_feature_flag_result( ) ) # Ensure non-None values for type checking - return self._get_feature_flag_result_with_context( - key, - distinct_id, - override_match_value, - groups or {}, - person_properties or {}, - group_properties or {}, - only_evaluate_locally, - send_feature_flag_events, - disable_geoip, - device_id, - ) + groups = groups or {} + person_properties = person_properties or {} + group_properties = group_properties or {} + + flag_result = None + flag_details = None + # Whether flag_details supplied the value this read reports. Only then may the + # read report config version 2 attribution or send $experiment_exposure. + value_from_details = False + request_id = None + evaluated_at = None + feature_flag_error: Optional[str] = None + remote_minimal_flag_called_events = False - def _get_feature_flag_result_with_context( - self, - key, - distinct_id, - override_match_value, - groups, - person_properties, - group_properties, - only_evaluate_locally, - send_feature_flag_events, - disable_geoip, - device_id, - ): - read = _FlagReadResult() # Resolve device_id from context if not provided if device_id is None: device_id = get_context_device_id() @@ -4916,16 +4819,40 @@ def _get_feature_flag_result_with_context( group_properties, device_id, ) + local_definition_version = snapshot["flag_definition_version"] flag_was_locally_evaluated = flag_value is not None if flag_value is not None: - read.result = self._resolve_local_flag_result( - key, - distinct_id, - flag_value, - override_match_value, - snapshot, + lookup_match_value = ( + override_match_value if override_match_value is not None else flag_value ) + payload = ( + self._compute_payload_locally( + key, lookup_match_value, _definition_snapshot=snapshot + ) + if lookup_match_value is not None + else None + ) + flag_result = FeatureFlagResult.from_value_and_payload( + key, lookup_match_value, payload + ) + + # Cache the local evaluation, not a payload lookup override. + cached_flag_result = flag_result + if override_match_value is not None: + cached_flag_result = FeatureFlagResult.from_value_and_payload( + key, + flag_value, + self._compute_payload_locally( + key, flag_value, _definition_snapshot=snapshot + ), + ) + if self.flag_cache and cached_flag_result: + # The cache rejects invalidated generations, including writes + # already in flight when new definitions are published. + self.flag_cache.set_cached_flag( + distinct_id, key, cached_flag_result, local_definition_version + ) elif only_evaluate_locally: if self.feature_flags is None: self.log.warning( @@ -4933,227 +4860,130 @@ def _get_feature_flag_result_with_context( "Returning None. You can call load_feature_flags() to load flags explicitly." ) else: - self._get_remote_flag_result( - read, - key, - distinct_id, - groups, - person_properties, - group_properties, - disable_geoip, - device_id, - override_match_value, - snapshot["flag_definition_version"], - ) + try: + ( + flag_details, + request_id, + evaluated_at, + errors_while_computing, + remote_minimal_flag_called_events, + ) = self._get_feature_flag_details_from_server( + key, + distinct_id, + groups, + person_properties, + group_properties, + disable_geoip, + device_id=device_id, + ) + errors = [] + if errors_while_computing: + errors.append(FeatureFlagError.ERRORS_WHILE_COMPUTING) + if flag_details is None: + errors.append(FeatureFlagError.FLAG_MISSING) + elif flag_details._server_marked_failed: + errors.append(FeatureFlagError.EVALUATION_FAILED) + if errors: + feature_flag_error = ",".join(errors) - if send_feature_flag_events: - self._capture_flag_read_result( - read, - key, - distinct_id, - snapshot, - flag_was_locally_evaluated, - groups, - disable_geoip, - ) - return read.result + flag_result = FeatureFlagResult.from_flag_details( + flag_details, override_match_value + ) - def _resolve_local_flag_result( - self, key, distinct_id, flag_value, override_match_value, snapshot - ): - local_definition_version = snapshot["flag_definition_version"] - lookup_match_value = ( - override_match_value if override_match_value is not None else flag_value - ) - payload = ( - self._compute_payload_locally( - key, lookup_match_value, _definition_snapshot=snapshot - ) - if lookup_match_value is not None - else None - ) - flag_result = FeatureFlagResult.from_value_and_payload( - key, lookup_match_value, payload - ) + if ( + flag_details is not None + and flag_details._malformed_field is not None + ): + # The record could not be read, so it reads as disabled. It must + # not replace the last good cached value, which it falls back to + # like a failed request, and it reports what a failed request + # reports: an unknown error and no request details. + feature_flag_error = FeatureFlagError.UNKNOWN_ERROR + request_id = None + evaluated_at = None + flag_result = ( + self._get_stale_flag_fallback(distinct_id, key) or flag_result + ) + # The request-start generation is an invalidation boundary, not + # a claim about the server's definitions. Refresh rejects late writes. + elif self.flag_cache and flag_result: + self.flag_cache._set_cached_remote_flag( + distinct_id, key, flag_result, local_definition_version + ) - # Cache the local evaluation, not a payload lookup override. - cached_flag_result = flag_result - if override_match_value is not None: - cached_flag_result = FeatureFlagResult.from_value_and_payload( - key, - flag_value, - self._compute_payload_locally( - key, flag_value, _definition_snapshot=snapshot - ), - ) - if self.flag_cache and cached_flag_result: - # The cache rejects invalidated generations, including writes - # already in flight when new definitions are published. - self.flag_cache.set_cached_flag( - distinct_id, key, cached_flag_result, local_definition_version - ) - return flag_result + self.log.debug( + f"Successfully computed flag remotely: #{key} -> #{flag_result}" + ) + # A successful payload override reports the caller's value. A failed + # record keeps its config version and reason code, never the override. + value_from_details = flag_details is not None and ( + override_match_value is None or flag_details._server_marked_failed + ) + except QuotaLimitError as e: + self.log.warning(f"[FEATURE FLAGS] Quota limit exceeded: {e}") + feature_flag_error = FeatureFlagError.QUOTA_LIMITED + flag_result = self._get_stale_flag_fallback(distinct_id, key) + except RequestsTimeout as e: + self.log.warning(f"[FEATURE FLAGS] Request timed out: {e}") + feature_flag_error = FeatureFlagError.TIMEOUT + flag_result = self._get_stale_flag_fallback(distinct_id, key) + except RequestsConnectionError as e: + self.log.warning(f"[FEATURE FLAGS] Connection error: {e}") + feature_flag_error = FeatureFlagError.CONNECTION_ERROR + flag_result = self._get_stale_flag_fallback(distinct_id, key) + except APIError as e: + self.log.warning(f"[FEATURE FLAGS] API error: {e}") + feature_flag_error = FeatureFlagError.api_error(e.status) + flag_result = self._get_stale_flag_fallback(distinct_id, key) + except Exception as e: + self.log.exception(f"[FEATURE FLAGS] Unable to get flag remotely: {e}") + feature_flag_error = FeatureFlagError.UNKNOWN_ERROR + flag_result = self._get_stale_flag_fallback(distinct_id, key) - def _get_remote_flag_result( - self, - read, - key, - distinct_id, - groups, - person_properties, - group_properties, - disable_geoip, - device_id, - override_match_value, - local_definition_version, - ): - try: - ( - read.details, - read.request_id, - read.evaluated_at, - errors_while_computing, - read.minimal_flag_called_events, - ) = self._get_feature_flag_details_from_server( - key, + if send_feature_flag_events: + # Locally-evaluated flags carry has_experiment in the stored definition; + # remotely-evaluated flags carry it in the response metadata. None when + # the server (older deployment) does not report it. + has_experiment: Optional[bool] = None + # Source the gate the same way as has_experiment above; see + # _capture_feature_flag_called_if_needed for why. + minimal_flag_called_events = self._minimal_flag_called_events + # Remotely-evaluated flags carry id and version in the response metadata; + # locally-evaluated flags read them from the definition that produced the value. + local_flag_id: Optional[int] = None + local_flag_version: Optional[int] = None + if flag_was_locally_evaluated: + local_def = snapshot["flags_by_key"].get(key) + if isinstance(local_def, dict): + has_experiment = _parse_has_experiment( + local_def.get("has_experiment") + ) + local_flag_id = local_def.get("id") + local_flag_version = local_def.get("version") + elif isinstance(flag_details, FeatureFlag): + has_experiment = _metadata_has_experiment(flag_details.metadata) + minimal_flag_called_events = remote_minimal_flag_called_events + + self._capture_feature_flag_called( distinct_id, + key, + flag_result.get_value() if flag_result else None, + flag_result.payload if flag_result else None, + flag_was_locally_evaluated, groups, - person_properties, - group_properties, disable_geoip, - device_id=device_id, + request_id, + evaluated_at, + flag_details, + feature_flag_error, + has_experiment, + minimal_flag_called_events, + local_flag_id=local_flag_id, + local_flag_version=local_flag_version, + value_from_details=value_from_details, ) - self._resolve_remote_flag_result( - read, - key, - distinct_id, - override_match_value, - local_definition_version, - errors_while_computing, - ) - - self.log.debug( - f"Successfully computed flag remotely: #{key} -> #{read.result}" - ) - # A successful payload override reports the caller's value. A failed - # record keeps its config version and reason code, never the override. - read.value_from_details = read.details is not None and ( - override_match_value is None or read.details._server_marked_failed - ) - except QuotaLimitError as e: - self.log.warning(f"[FEATURE FLAGS] Quota limit exceeded: {e}") - read.error = FeatureFlagError.QUOTA_LIMITED - read.result = self._get_stale_flag_fallback(distinct_id, key) - except RequestsTimeout as e: - self.log.warning(f"[FEATURE FLAGS] Request timed out: {e}") - read.error = FeatureFlagError.TIMEOUT - read.result = self._get_stale_flag_fallback(distinct_id, key) - except RequestsConnectionError as e: - self.log.warning(f"[FEATURE FLAGS] Connection error: {e}") - read.error = FeatureFlagError.CONNECTION_ERROR - read.result = self._get_stale_flag_fallback(distinct_id, key) - except APIError as e: - self.log.warning(f"[FEATURE FLAGS] API error: {e}") - read.error = FeatureFlagError.api_error(e.status) - read.result = self._get_stale_flag_fallback(distinct_id, key) - except Exception as e: - self.log.exception(f"[FEATURE FLAGS] Unable to get flag remotely: {e}") - read.error = FeatureFlagError.UNKNOWN_ERROR - read.result = self._get_stale_flag_fallback(distinct_id, key) - - def _resolve_remote_flag_result( - self, - read, - key, - distinct_id, - override_match_value, - local_definition_version, - errors_while_computing, - ): - read.error = self._remote_flag_result_error( - errors_while_computing, read.details - ) - read.result = FeatureFlagResult.from_flag_details( - read.details, override_match_value - ) - - if read.details is not None and read.details._malformed_field is not None: - # The record could not be read, so it reads as disabled. It must - # not replace the last good cached value, which it falls back to - # like a failed request, and it reports what a failed request - # reports: an unknown error and no request details. - read.error = FeatureFlagError.UNKNOWN_ERROR - read.request_id = None - read.evaluated_at = None - read.result = self._get_stale_flag_fallback(distinct_id, key) or read.result - # The request-start generation is an invalidation boundary, not - # a claim about the server's definitions. Refresh rejects late writes. - elif self.flag_cache and read.result: - self.flag_cache._set_cached_remote_flag( - distinct_id, key, read.result, local_definition_version - ) - - @staticmethod - def _remote_flag_result_error(errors_while_computing, flag_details): - errors = [] - if errors_while_computing: - errors.append(FeatureFlagError.ERRORS_WHILE_COMPUTING) - if flag_details is None: - errors.append(FeatureFlagError.FLAG_MISSING) - elif flag_details._server_marked_failed: - errors.append(FeatureFlagError.EVALUATION_FAILED) - return ",".join(errors) if errors else None - - def _capture_flag_read_result( - self, - read, - key, - distinct_id, - snapshot, - flag_was_locally_evaluated, - groups, - disable_geoip, - ): - # Locally-evaluated flags carry has_experiment in the stored definition; - # remotely-evaluated flags carry it in the response metadata. None when - # the server (older deployment) does not report it. - has_experiment: Optional[bool] = None - # Source the gate the same way as has_experiment above; see - # _capture_feature_flag_called_if_needed for why. - minimal_flag_called_events = self._minimal_flag_called_events - # Remotely-evaluated flags carry id and version in the response metadata; - # locally-evaluated flags read them from the definition that produced the value. - local_flag_id: Optional[int] = None - local_flag_version: Optional[int] = None - if flag_was_locally_evaluated: - local_def = snapshot["flags_by_key"].get(key) - if isinstance(local_def, dict): - has_experiment = _parse_has_experiment(local_def.get("has_experiment")) - local_flag_id = local_def.get("id") - local_flag_version = local_def.get("version") - elif isinstance(read.details, FeatureFlag): - has_experiment = _metadata_has_experiment(read.details.metadata) - minimal_flag_called_events = read.minimal_flag_called_events - - self._capture_feature_flag_called( - distinct_id, - key, - read.result.get_value() if read.result else None, - read.result.payload if read.result else None, - flag_was_locally_evaluated, - groups, - disable_geoip, - read.request_id, - read.evaluated_at, - read.details, - read.error, - has_experiment, - minimal_flag_called_events, - local_flag_id=local_flag_id, - local_flag_version=local_flag_version, - value_from_details=read.value_from_details, - ) + return flag_result def get_feature_flag_result( self, @@ -5467,7 +5297,14 @@ def _capture_feature_flag_called( properties["$feature_flag_request_id"] = request_id if evaluated_at: properties["$feature_flag_evaluated_at"] = evaluated_at - self._add_remote_flag_called_metadata(properties, flag_details) + if isinstance(flag_details, FeatureFlag): + if flag_details.reason and flag_details.reason.description: + properties["$feature_flag_reason"] = flag_details.reason.description + if isinstance(flag_details.metadata, FlagMetadata): + if flag_details.metadata.version: + properties["$feature_flag_version"] = flag_details.metadata.version + if flag_details.metadata.id: + properties["$feature_flag_id"] = flag_details.metadata.id if local_flag_version: properties["$feature_flag_version"] = local_flag_version if local_flag_id: @@ -5488,17 +5325,6 @@ def _capture_feature_flag_called( value_from_details=value_from_details, ) - @staticmethod - def _add_remote_flag_called_metadata(properties, flag_details): - if isinstance(flag_details, FeatureFlag): - if flag_details.reason and flag_details.reason.description: - properties["$feature_flag_reason"] = flag_details.reason.description - if isinstance(flag_details.metadata, FlagMetadata): - if flag_details.metadata.version: - properties["$feature_flag_version"] = flag_details.metadata.version - if flag_details.metadata.id: - properties["$feature_flag_id"] = flag_details.metadata.id - def _capture_feature_flag_called_if_needed( self, *, @@ -5569,18 +5395,12 @@ def get_remote_config_payload(self, key: str): return None try: - request_remote_config = ( - _remote_config_with_identity - if self._request_identity_kwargs() - else remote_config - ) - return request_remote_config( + return remote_config( self.personal_api_key, self.api_key, self.host, key, timeout=self.feature_flags_request_timeout_seconds, - **self._request_identity_kwargs(), ) except Exception as e: self.log.exception( @@ -5836,9 +5656,15 @@ def evaluate_flags( """ host = self._get_feature_flag_evaluations_host() - distinct_id, device_id = self._resolve_feature_flag_identity( - distinct_id, device_id - ) + if distinct_id is None: + distinct_id = get_context_distinct_id() + + # Resolve device_id from context when not explicitly provided. The context value + # may be set via tracing headers; the explicit parameter is an override for callers + # who want to bypass it. Used by the remote /flags request for experience-continuity + # flag matching. + if device_id is None: + device_id = get_context_device_id() if not distinct_id or self.disabled: # Empty snapshot. The class short-circuits on empty distinct_id so calling @@ -5862,45 +5688,14 @@ def evaluate_flags( ) ) groups = groups or {} - return self._evaluate_flags_with_context( - host, - distinct_id, - groups, - person_properties, - group_properties, - only_evaluate_locally, - disable_geoip, - flag_keys, - device_id, - ) - - @staticmethod - def _resolve_feature_flag_identity(distinct_id, device_id): - if distinct_id is None: - distinct_id = get_context_distinct_id() - - # Resolve device_id from context when not explicitly provided. The context value - # may be set via tracing headers; the explicit parameter is an override for callers - # who want to bypass it. Used by the remote /flags request for experience-continuity - # flag matching. - if device_id is None: - device_id = get_context_device_id() - - return distinct_id, device_id - - def _evaluate_flags_with_context( - self, - host, - distinct_id, - groups, - person_properties, - group_properties, - only_evaluate_locally, - disable_geoip, - flag_keys, - device_id, - ) -> FeatureFlagEvaluations: requested_keys = set(flag_keys) if flag_keys else None + + records: Dict[str, _EvaluatedFlagRecord] = {} + request_id: Optional[str] = None + evaluated_at: Optional[int] = None + errors_while_computing = False + quota_limited = False + locally_evaluated_keys: set[str] = set() unresolved: Dict[str, UnresolvedFlagReason] = {} # Try local evaluation first when the poller has loaded definitions. local_person_properties = self._person_properties_for_local_evaluation( @@ -5923,129 +5718,90 @@ def _evaluate_flags_with_context( minimal_flag_called_events = definition_snapshot.get( "minimal_flag_called_events", False ) - result = _FlagEvaluationResult( - records=self._local_evaluation_records(local_result, definition_snapshot), - minimal_flag_called_events=minimal_flag_called_events, - ) - if requested_keys and not requested_keys.issubset(result.records): + feature_flags_by_key = definition_snapshot["flags_by_key"] + local_flags = local_result.get("featureFlags") or {} + local_payloads = local_result.get("featureFlagPayloads") or {} + if requested_keys and not requested_keys.issubset(local_flags): # A requested flag may have been created since the last definitions poll. # Ask /flags for the caller's original scope unless this is a local-only call. fallback_to_server = True + for key, value in local_flags.items(): + flag_def = feature_flags_by_key.get(key) or {} + records[key] = _LocalFlagRecord( + key=key, + enabled=value is not False, + variant=value if isinstance(value, str) else None, + payload=_parse_flag_payload(local_payloads.get(key)), + id=flag_def.get("id"), + version=flag_def.get("version"), + reason="Evaluated locally", + locally_evaluated=True, + has_experiment=_parse_has_experiment(flag_def.get("has_experiment")), + ) + locally_evaluated_keys.add(key) + # Fall back to remote evaluation for any flags the poller couldn't resolve locally. # Use the flags decision path directly so the resulting records carry id/version/reason # and fired ``$feature_flag_called`` events match what ``get_feature_flag()`` emits. if fallback_to_server and not only_evaluate_locally: - self._evaluate_flags_remotely( - result, - distinct_id, - groups, - person_properties, - group_properties, - disable_geoip, - flag_keys, - device_id, - requested_keys, - ) + try: + response = self._get_flags_decision( + distinct_id, + groups=groups, + person_properties=person_properties, + group_properties=group_properties, + disable_geoip=disable_geoip, + flag_keys_to_evaluate=flag_keys, + device_id=device_id, + ) + request_id = response.get("requestId") + raw_evaluated_at = response.get("evaluatedAt") + evaluated_at = ( + raw_evaluated_at if isinstance(raw_evaluated_at, int) else None + ) + errors_while_computing = bool( + response.get("errorsWhileComputingFlags", False) + ) + minimal_flag_called_events = ( + response.get("minimalFlagCalledEvents") is True + ) + for key, detail in response.get("flags", {}).items(): + if requested_keys is not None and key not in requested_keys: + continue + if key in locally_evaluated_keys: + continue + records[key] = _RemoteFlagRecord(detail) + except QuotaLimitError as e: + self.log.warning(f"[FEATURE FLAGS] Quota limit exceeded: {e}") + quota_limited = True + except Exception as e: + self.log.exception( + f"[FEATURE FLAGS] Unable to evaluate flags remotely: {e}" + ) return FeatureFlagEvaluations( host=host, distinct_id=str(distinct_id), - flags=result.records, + flags=records, groups=groups, disable_geoip=disable_geoip, - request_id=result.request_id, - evaluated_at=result.evaluated_at, - errors_while_computing=result.errors_while_computing, - quota_limited=result.quota_limited, - minimal_flag_called_events=result.minimal_flag_called_events, + request_id=request_id, + evaluated_at=evaluated_at, + errors_while_computing=errors_while_computing, + quota_limited=quota_limited, + minimal_flag_called_events=minimal_flag_called_events, unresolved_flags={ key: reason for key, reason in unresolved.items() - if key not in result.records + if key not in records or ( - isinstance(record := result.records[key], _RemoteFlagRecord) + isinstance(record := records[key], _RemoteFlagRecord) and record.details._server_marked_failed ) }, ) - @staticmethod - def _local_evaluation_records(local_result, definition_snapshot): - records: Dict[str, _EvaluatedFlagRecord] = {} - feature_flags_by_key = definition_snapshot["flags_by_key"] - local_flags = local_result.get("featureFlags") or {} - local_payloads = local_result.get("featureFlagPayloads") or {} - for key, value in local_flags.items(): - flag_def = feature_flags_by_key.get(key) or {} - records[key] = _LocalFlagRecord( - key=key, - enabled=value is not False, - variant=value if isinstance(value, str) else None, - payload=_parse_flag_payload(local_payloads.get(key)), - id=flag_def.get("id"), - version=flag_def.get("version"), - reason="Evaluated locally", - locally_evaluated=True, - has_experiment=_parse_has_experiment(flag_def.get("has_experiment")), - ) - - return records - - def _evaluate_flags_remotely( - self, - result, - distinct_id, - groups, - person_properties, - group_properties, - disable_geoip, - flag_keys, - device_id, - requested_keys, - ): - local_keys = set(result.records) - try: - response = self._get_flags_decision( - distinct_id, - groups=groups, - person_properties=person_properties, - group_properties=group_properties, - disable_geoip=disable_geoip, - flag_keys_to_evaluate=flag_keys, - device_id=device_id, - ) - result.request_id = response.get("requestId") - raw_evaluated_at = response.get("evaluatedAt") - result.evaluated_at = ( - raw_evaluated_at if isinstance(raw_evaluated_at, int) else None - ) - result.errors_while_computing = bool( - response.get("errorsWhileComputingFlags", False) - ) - result.minimal_flag_called_events = ( - response.get("minimalFlagCalledEvents") is True - ) - self._merge_remote_evaluation_records( - result.records, response, requested_keys, local_keys - ) - except QuotaLimitError as e: - self.log.warning(f"[FEATURE FLAGS] Quota limit exceeded: {e}") - result.quota_limited = True - except Exception as e: - self.log.exception( - f"[FEATURE FLAGS] Unable to evaluate flags remotely: {e}" - ) - - @staticmethod - def _merge_remote_evaluation_records(records, response, requested_keys, local_keys): - for key, detail in response.get("flags", {}).items(): - if requested_keys is not None and key not in requested_keys: - continue - if key in local_keys: - continue - records[key] = _RemoteFlagRecord(detail) - _feature_flag_evaluations_host_cache: Optional[_FeatureFlagEvaluationsHost] = None def _get_feature_flag_evaluations_host(self) -> _FeatureFlagEvaluationsHost: @@ -6080,19 +5836,43 @@ def _get_all_flags_and_payloads_locally( snapshot = self._local_evaluation_snapshot() # If loading in previous line failed if snapshot["flags"]: - fallback_to_flags = self._evaluate_local_flag_set( - snapshot, - distinct_id, - groups, - person_properties, - group_properties, - warn_on_unknown_groups, - flag_keys_to_evaluate, - device_id, - unresolved, - flags, - payloads, - ) + # Filter flags based on flag_keys_to_evaluate if provided + flags_to_process = snapshot["flags"] + if flag_keys_to_evaluate: + flag_keys_set = set(flag_keys_to_evaluate) + flags_to_process = [ + flag for flag in snapshot["flags"] if flag["key"] in flag_keys_set + ] + + for flag in flags_to_process: + try: + flags[flag["key"]] = self._compute_flag_locally( + flag, + distinct_id, + groups=groups, + person_properties=person_properties, + group_properties=group_properties, + warn_on_unknown_groups=warn_on_unknown_groups, + device_id=device_id, + _definition_snapshot=snapshot, + ) + matched_payload = self._compute_payload_locally( + flag["key"], + flags[flag["key"]], + _definition_snapshot=snapshot, + ) + if matched_payload is not None: + payloads[flag["key"]] = matched_payload + except (InconclusiveMatchError, RequiresServerEvaluation) as e: + # No need to log this, since it's just telling us to fall back to `/flags` + fallback_to_flags = True + if unresolved is not None: + unresolved[flag["key"]] = e.reason + except Exception as e: + self.log.exception( + f"[FEATURE FLAGS] Error while computing variant and payload: {e}" + ) + fallback_to_flags = True else: fallback_to_flags = True @@ -6105,67 +5885,6 @@ def _get_all_flags_and_payloads_locally( snapshot, ) - @staticmethod - def _select_flags_for_local_evaluation(snapshot, flag_keys_to_evaluate): - # Filter flags based on flag_keys_to_evaluate if provided - flags_to_process = snapshot["flags"] - if flag_keys_to_evaluate: - flag_keys_set = set(flag_keys_to_evaluate) - flags_to_process = [ - flag for flag in snapshot["flags"] if flag["key"] in flag_keys_set - ] - - return flags_to_process - - def _evaluate_local_flag_set( - self, - snapshot, - distinct_id, - groups, - person_properties, - group_properties, - warn_on_unknown_groups, - flag_keys_to_evaluate, - device_id, - unresolved, - flags, - payloads, - ): - fallback_to_flags = False - flags_to_process = self._select_flags_for_local_evaluation( - snapshot, flag_keys_to_evaluate - ) - for flag in flags_to_process: - try: - flags[flag["key"]] = self._compute_flag_locally( - flag, - distinct_id, - groups=groups, - person_properties=person_properties, - group_properties=group_properties, - warn_on_unknown_groups=warn_on_unknown_groups, - device_id=device_id, - _definition_snapshot=snapshot, - ) - matched_payload = self._compute_payload_locally( - flag["key"], - flags[flag["key"]], - _definition_snapshot=snapshot, - ) - if matched_payload is not None: - payloads[flag["key"]] = matched_payload - except (InconclusiveMatchError, RequiresServerEvaluation) as e: - # No need to log this, since it's just telling us to fall back to `/flags` - fallback_to_flags = True - if unresolved is not None: - unresolved[flag["key"]] = e.reason - except Exception as e: - self.log.exception( - f"[FEATURE FLAGS] Error while computing variant and payload: {e}" - ) - fallback_to_flags = True - return fallback_to_flags - def _initialize_flag_cache(self, cache_url): """Initialize feature flag cache for graceful degradation during service outages. @@ -6216,57 +5935,48 @@ def _initialize_flag_cache(self, cache_url): return FlagCache(size, ttl) elif scheme in ("redis", "rediss"): - return self._initialize_redis_flag_cache(parsed, ttl) - else: - raise ValueError( - f"Unknown cache URL scheme: {scheme}. Supported schemes: memory, redis, rediss" - ) - - except Exception as e: - self.log.warning( - f"[FEATURE FLAGS] Failed to parse cache URL '{cache_url}': {e}" - ) - return None + try: + # Not worth importing redis if we're not using it + import redis - def _initialize_redis_flag_cache(self, parsed, ttl): - try: - # Not worth importing redis if we're not using it - import redis + redis_url = f"{parsed.scheme}://" + if parsed.username or parsed.password: + redis_url += f"{parsed.username or ''}:{parsed.password or ''}@" + host = parsed.hostname or "localhost" + if ":" in host: + host = f"[{host}]" + redis_url += f"{host}:{parsed.port or 6379}" + if parsed.path: + redis_url += parsed.path - redis_url = self._redis_flag_cache_url(parsed) + client = redis.from_url(redis_url) - client = redis.from_url(redis_url) + # Test connection before using it + client.ping() - # Test connection before using it - client.ping() + return RedisFlagCache(client, default_ttl=ttl) - return RedisFlagCache(client, default_ttl=ttl) + except ImportError: + self.log.warning( + "[FEATURE FLAGS] Redis not available, flag caching disabled" + ) + return None + except Exception as e: + self.log.warning( + f"[FEATURE FLAGS] Redis connection failed: {e}, flag caching disabled" + ) + return None + else: + raise ValueError( + f"Unknown cache URL scheme: {scheme}. Supported schemes: memory, redis, rediss" + ) - except ImportError: - self.log.warning( - "[FEATURE FLAGS] Redis not available, flag caching disabled" - ) - return None except Exception as e: self.log.warning( - f"[FEATURE FLAGS] Redis connection failed: {e}, flag caching disabled" + f"[FEATURE FLAGS] Failed to parse cache URL '{cache_url}': {e}" ) return None - @staticmethod - def _redis_flag_cache_url(parsed): - redis_url = f"{parsed.scheme}://" - if parsed.username or parsed.password: - redis_url += f"{parsed.username or ''}:{parsed.password or ''}@" - host = parsed.hostname or "localhost" - if ":" in host: - host = f"[{host}]" - redis_url += f"{host}:{parsed.port or 6379}" - if parsed.path: - redis_url += parsed.path - - return redis_url - def feature_flag_definitions(self): """ Return feature flag definitions loaded for local evaluation. diff --git a/posthog/consumer.py b/posthog/consumer.py index d9de6d441..265cb9e77 100644 --- a/posthog/consumer.py +++ b/posthog/consumer.py @@ -6,30 +6,37 @@ from posthog._logging import _configure_posthog_logging from posthog.capture_compression import CaptureCompression -from posthog.capture_mode import CaptureMode -from posthog.capture_v1 import _backoff, _send_v1_batch +from posthog.capture_send import ( + _CAPTURE_V1_PATH, + _capture_loss_message, + _send_v1_batch, +) from posthog.request import ( - EVENTS_ENDPOINT, USER_AGENT as _USER_AGENT, - APIError, DatetimeSerializer, - batch_post, ) from queue import Empty -MAX_MSG_SIZE = 900 * 1024 # 900KiB per event - -# AI events carry LLM inputs/outputs and post to a dedicated endpoint whose -# pipeline accepts larger messages than analytics ingestion, so the AI lane -# grants a higher per-event ceiling. `next()` appends an item before checking -# BATCH_SIZE_LIMIT, so worst-case request body is BATCH_SIZE_LIMIT + -# AI_MAX_MSG_SIZE (~13MiB) — keep that sum under the 20MiB server body cap. -AI_MAX_MSG_SIZE = 8 * 1024 * 1024 # 8MiB per event - -# The maximum request body size is currently 20MiB, let's be conservative -# in case we want to lower it in the future. +# Capture's request body limit. An analytics event larger than this can never +# be accepted, so the SDK drops it locally; anything smaller is sent, and +# capture reports an event over its own per-event limit in the response. +MAX_MSG_SIZE = 10 * 1024 * 1024 + +# The AI endpoint's per-event ceiling. The endpoint applies it to the +# serialized properties alone. +AI_MAX_PROPERTIES_SIZE = 8 * 1024 * 1024 +# The local guard measures the whole event, not only its properties, so it +# allows this much more to keep events at the endpoint's ceiling. +AI_ENVELOPE_HEADROOM = 64 * 1024 +# The AI lane's per-event guard, and the upper bound for +# `capture_ai_max_event_bytes`. +AI_MAX_MSG_SIZE = AI_MAX_PROPERTIES_SIZE + AI_ENVELOPE_HEADROOM + +# A batch closes before it appends an event that would take it past this, so +# a request carries at most this much event data, or one larger event alone. +# Half of capture's request body limit, which applies before decompression. BATCH_SIZE_LIMIT = 5 * 1024 * 1024 _configure_posthog_logging() @@ -73,17 +80,14 @@ def draining(self, consumer) -> bool: with self._queue.mutex: return self._requests > 0 and (consumer.running or consumer._drain_on_stop) - def _is_draining_locked(self, consumer) -> bool: - return self._requests > 0 and ( - consumer is None or consumer.running or consumer._drain_on_stop - ) - def get(self, timeout: float, consumer=None): """Get an item, or wake with ``Empty`` when draining or stopping.""" with self._queue.not_empty: deadline = time.monotonic() + timeout while True: - draining = self._is_draining_locked(consumer) + draining = self._requests > 0 and ( + consumer is None or consumer.running or consumer._drain_on_stop + ) if consumer is not None and not consumer.running and not draining: raise Empty if self._queue._qsize(): @@ -112,13 +116,11 @@ def __init__( host=None, on_error=None, flush_interval=5.0, - gzip=False, - retries=10, + retries=3, timeout: float = 15, historical_migration=False, - endpoint=EVENTS_ENDPOINT, + endpoint=_CAPTURE_V1_PATH, max_msg_size=MAX_MSG_SIZE, - capture_mode=CaptureMode.V0, capture_compression=CaptureCompression.NONE, ): """Create a consumer thread.""" @@ -131,10 +133,8 @@ def __init__( self.host = host self.on_error = on_error self.queue = queue - self.gzip = gzip self.endpoint = endpoint self.max_msg_size = max_msg_size - self.capture_mode = capture_mode self.capture_compression = capture_compression self._sdk_info = _USER_AGENT self._drain_signal: Optional[_DrainSignal] = None @@ -183,13 +183,14 @@ def upload(self): self.request(batch) success = True except Exception as e: - self.log.error("error uploading: %s", e) success = False if self.on_error: try: self.on_error(e, batch) - except Exception as e: - self.log.error("on_error handler failed: %s", e) + except Exception as callback_error: + self.log.error("on_error handler failed: %s", callback_error) + else: + self.log.error(_capture_loss_message(e, len(batch), self.endpoint)) finally: # mark items as acknowledged from queue for item in batch: @@ -216,44 +217,6 @@ def _can_upload(self) -> bool: with self.queue.mutex: return self.running or self._drain_on_stop - def _event_size(self, item) -> Optional[int]: - try: - item_size = len(json.dumps(item, cls=DatetimeSerializer).encode()) - except Exception: - # Callback-modified events can still contain invalid mapping - # keys or circular references. Never log the payload here. - self.log.error("Unable to serialize queued event for sizing, dropping.") - return None - if item_size > self.max_msg_size: - # Log only name and size: AI events may carry unredacted - # multimodal payloads that must not leak into logs. - self.log.error( - "Event %s (%d bytes) exceeds the %dKiB limit for %s, dropping.", - item.get("event") if isinstance(item, dict) else type(item), - item_size, - self.max_msg_size // 1024, - self.endpoint, - ) - return None - return item_size - - def _next_queue_timeout(self, start_time: float) -> Optional[float]: - # While draining we take only what is already queued, never waiting - # for `flush_interval` to elapse or for `flush_at` to be reached. - draining = self._draining() - if not self.running and not draining: - return None - remaining = self.flush_interval - (time.monotonic() - start_time) - if not draining and remaining <= 0: - return None - - return 0 if draining else remaining - - @staticmethod - def _acknowledge(queue, count: int) -> None: - for _ in range(count): - queue.task_done() - def next(self): """Return the next batch of items to upload.""" queue = self.queue @@ -265,24 +228,57 @@ def next(self): try: while len(items) < self.flush_at: - timeout = self._next_queue_timeout(start_time) - if timeout is None: + # While draining we take only what is already queued, never waiting + # for `flush_interval` to elapse or for `flush_at` to be reached. + draining = self._draining() + if not self.running and not draining: + break + remaining = self.flush_interval - (time.monotonic() - start_time) + if not draining and remaining <= 0: break try: if self._drain_signal is not None: item = self._drain_signal.get( - timeout=timeout, + timeout=0 if draining else remaining, consumer=self, ) else: - item = queue.get(block=True, timeout=timeout) + item = queue.get(block=True, timeout=remaining) pending_items += 1 - item_size = self._event_size(item) - if item_size is None: + try: + item_size = len( + json.dumps( + item, cls=DatetimeSerializer, allow_nan=False + ).encode() + ) + except Exception: + # Callback-modified events can still contain invalid mapping + # keys or circular references. Never log the payload here. + self.log.error( + "Unable to serialize queued event for sizing, dropping." + ) queue.task_done() pending_items -= 1 continue + if item_size > self.max_msg_size: + # Log only name and size: AI events may carry unredacted + # multimodal payloads that must not leak into logs. + self.log.error( + "Event %s (%d bytes) exceeds the %dKiB limit for %s, dropping.", + item.get("event") if isinstance(item, dict) else type(item), + item_size, + self.max_msg_size // 1024, + self.endpoint, + ) + queue.task_done() + pending_items -= 1 + continue + if items and total_size + item_size > BATCH_SIZE_LIMIT: + self._return_to_queue_head(item) + pending_items -= 1 + self.log.debug("hit batch size limit (size: %d)", total_size) + break items.append(item) total_size += item_size if total_size >= BATCH_SIZE_LIMIT: @@ -291,76 +287,40 @@ def next(self): except Empty: break except BaseException: - self._acknowledge(queue, pending_items) + for _ in range(pending_items): + queue.task_done() raise if not self._can_upload(): - self._acknowledge(queue, pending_items) + for _ in range(pending_items): + queue.task_done() return [] return items - def request(self, batch): - """Upload the batch via the wire protocol selected by `capture_mode`. + def _return_to_queue_head(self, item) -> None: + """Put a dequeued event back at the head of the queue for the next batch. - V1 uses the partial-retry submitter (which posts to its own path); V0 - posts the batch to this consumer's `endpoint`. + The event stays counted in ``unfinished_tasks``, because it was never + marked done. Keeping it in the queue, not in the consumer, means a + stop, a discard or a fork accounts for it like any other queued event. """ - if self.capture_mode == CaptureMode.V1: - _send_v1_batch( - self.api_key, - self.host, - batch, - compression=self.capture_compression, - timeout=self.timeout, - max_retries=self.retries, - historical_migration=self.historical_migration, - sdk_info=self._sdk_info, - ) - return - self._send(batch, self.endpoint) - - def _send(self, batch, path): - """Attempt to upload a single batch to `path`, retrying before raising an error""" - - def is_retryable(exc): - if isinstance(exc, APIError): - # retry on server errors and client errors - # with 408 (request timeout) or 429 (rate limited), - # don't retry on other client errors - if isinstance(exc.status, int): - return not ( - (400 <= exc.status < 500) and exc.status not in (408, 429) - ) - return False - else: - # retry on all other errors (eg. network) - return True + queue = self.queue + with queue.not_empty: + queue.queue.appendleft(item) + queue.not_empty.notify() - last_exc = None - for attempt in range(self.retries + 1): - try: - batch_post( - self.api_key, - self.host, - gzip=self.gzip, - timeout=self.timeout, - batch=batch, - historical_migration=self.historical_migration, - path=path, - **( - {"_user_agent": self._sdk_info} - if self._sdk_info != _USER_AGENT - else {} - ), - ) - return - except Exception as e: - last_exc = e - if not is_retryable(e): - raise - if attempt < self.retries: - _backoff(attempt, getattr(e, "retry_after", None)) - - if last_exc: - raise last_exc + def request(self, batch): + """Upload the batch to this consumer's `endpoint` with the capture v1 + partial-retry submitter.""" + _send_v1_batch( + self.api_key, + self.host, + batch, + compression=self.capture_compression, + timeout=self.timeout, + max_retries=self.retries, + historical_migration=self.historical_migration, + sdk_info=self._sdk_info, + path=self.endpoint, + ) diff --git a/posthog/contexts.py b/posthog/contexts.py index 4acdf8abb..97e6a1300 100644 --- a/posthog/contexts.py +++ b/posthog/contexts.py @@ -29,6 +29,7 @@ def __init__( self.distinct_id: Optional[str] = None self.device_id: Optional[str] = None self.tags: Dict[str, Any] = {} + self.options: Dict[str, Any] = {} self.capture_exception_code_variables: Optional[bool] = None self.code_variables_mask_patterns: Optional[list] = None self.code_variables_ignore_patterns: Optional[list] = None @@ -47,6 +48,9 @@ def set_device_id(self, device_id: str): def add_tag(self, key: str, value: Any): self.tags[key] = value + def add_option(self, key: str, value: Any): + self.options[key] = value + def set_capture_exception_code_variables(self, enabled: bool): self.capture_exception_code_variables = enabled @@ -95,6 +99,13 @@ def collect_tags(self) -> Dict[str, Any]: return tags return self.tags.copy() + def collect_options(self) -> Dict[str, Any]: + if self.parent and not self.fresh: + options = self.parent.collect_options() + options.update(self.options) + return options + return self.options.copy() + def get_capture_exception_code_variables(self) -> Optional[bool]: if self.capture_exception_code_variables is not None: return self.capture_exception_code_variables @@ -305,6 +316,54 @@ def get_tags() -> Dict[str, Any]: return {} +def set_context_option(key: str, value: Any) -> None: + """ + Set a capture option for every event captured within the current context. + + Context options fill options an event leaves unset, before ``before_send`` + runs, so the hook sees them. They override the client's ``super_options``. + An event's own ``options`` override them, and ``before_send`` can change + them. Child contexts inherit them unless they are fresh. They never set + ``process_person_profile`` on identify-style events, such as ``$identify`` + or ``$set``, whose distinct ID the SDK did not generate: those default it + to ``True``. + + Args: + key: The option name, such as ``"process_person_profile"`` + value: The option value, sent as given + + Example: + ```python + with posthog.new_context(): + posthog.set_context_option("process_person_profile", False) + posthog.capture("health_check") + ``` + + Category: + Contexts + """ + current_context = _get_current_context() + if current_context: + current_context.add_option(key, value) + + +def get_context_options() -> Dict[str, Any]: + """ + Get all capture options from the current context. Note, modifying + the returned dictionary will not affect the current context. + + Returns: + Dict of all capture options in the current context + + Category: + Contexts + """ + current_context = _get_current_context() + if current_context: + return current_context.collect_options() + return {} + + def identify_context(distinct_id: str) -> None: """ Identify the current context with a distinct ID, associating all events captured in this or diff --git a/posthog/emails.py b/posthog/emails.py index 047119b99..1f0bfaec4 100644 --- a/posthog/emails.py +++ b/posthog/emails.py @@ -154,7 +154,7 @@ import requests from typing_extensions import NotRequired, Unpack -from .capture_v1 import _parse_retry_after +from .capture_send import _parse_retry_after from .request import ( EU_APP_ENDPOINT, US_APP_ENDPOINT, diff --git a/posthog/exception_utils.py b/posthog/exception_utils.py index 107973953..da0d1dbcd 100644 --- a/posthog/exception_utils.py +++ b/posthog/exception_utils.py @@ -647,6 +647,47 @@ def _normalize_exception_level(level): return _EXCEPTION_LEVELS.get(level.lower()) if isinstance(level, str) else None +# Exception properties the SDK or PostHog owns. A caller's per-call +# `properties` cannot set them. +_RESERVED_EXCEPTION_PROPERTIES = frozenset( + { + "$exception_list", + "$exception_level", + "$exception_source", + "$debug_images", + "$exception_handled", + "$exception_types", + "$exception_values", + "$exception_sources", + "$exception_functions", + "$exception_fingerprint_version", + "$exception_fingerprint_record", + "$exception_issue_id", + "$exception_release", + "$cymbal_errors", + } +) + + +def _exception_level(integration_level, level): + # type: (Any, Any) -> str + """An integration's level wins over the caller's ``level=``; an invalid value counts as unset.""" + return ( + _normalize_exception_level(integration_level) + or _normalize_exception_level(level) + or "error" + ) + + +def _without_reserved_exception_properties(properties): + # type: (Optional[Dict[str, Any]]) -> Dict[str, Any] + return { + key: value + for key, value in (properties or {}).items() + if key not in _RESERVED_EXCEPTION_PROPERTIES + } + + def _capture_exception_with_metadata(client, exception, capture_metadata, **kwargs): # type: (Any, ExceptionArg, _ExceptionCaptureMetadata, **Any) -> Optional[str] """Call capture_exception through the SDK-internal typed integration channel.""" diff --git a/posthog/integrations/asgi.py b/posthog/integrations/asgi.py index f20b4779b..72711d4e5 100644 --- a/posthog/integrations/asgi.py +++ b/posthog/integrations/asgi.py @@ -192,6 +192,12 @@ async def _resolve_callback_result(value): class PosthogASGIMiddleware: """Add PostHog context and automatic exception capture to an ASGI app. + It creates a context for each HTTP or WebSocket request and captures + exceptions that escape the app. In FastAPI or Starlette, add it with + ``app.add_middleware(PosthogASGIMiddleware, client=posthog)``. For Litestar, + another ASGI framework or a raw ASGI app, wrap the app with + ``app = PosthogASGIMiddleware(app, client=posthog)``. + Args: app: The downstream ASGI application. client: Optional destination for automatically captured exceptions. The diff --git a/posthog/integrations/celery.py b/posthog/integrations/celery.py index 0d59c2a52..165facb82 100644 --- a/posthog/integrations/celery.py +++ b/posthog/integrations/celery.py @@ -10,8 +10,8 @@ queue, retry count, duration, Celery version etc. - Any custom events captured inside a task (via ``client.capture``) are automatically enriched with the same Celery-specific properties via context tags. -- Propagates PostHog context (distinct ID, session ID, tags) from the producer - process to the worker process. +- Propagates PostHog context (distinct ID, session ID, tags, context options) + from the producer process to the worker process. Supports Celery 4.0+ (Message Protocol Version 2). @@ -82,6 +82,7 @@ CONTEXT_DISTINCT_ID_HEADER = "X-POSTHOG-DISTINCT-ID" CONTEXT_SESSION_ID_HEADER = "X-POSTHOG-SESSION-ID" CONTEXT_TAGS_HEADER = "X-POSTHOG-CONTEXT-TAGS" +CONTEXT_OPTIONS_HEADER = "X-POSTHOG-CONTEXT-OPTIONS" logger = logging.getLogger("posthog") @@ -101,8 +102,8 @@ class PosthogCeleryIntegration: capture_task_lifecycle_events: Whether to emit lifecycle events of the task such as "started", "success", "failure" etc. (default ``True``). propagate_context: Whether to propagate PostHog context (distinct - ID, session ID, tags) from the producer to the worker via task - headers (default ``True``). + ID, session ID, tags, context options) from the producer to the + worker via task headers (default ``True``). task_filter: Optional callback ``(task_name, task_properties) -> bool`` expected to return ``False`` if a given task should not be tracked. """ @@ -228,6 +229,7 @@ def _on_before_task_publish(self, *args, **kwargs): distinct_id = contexts.get_context_distinct_id() session_id = contexts.get_context_session_id() tags = contexts.get_tags() + options = contexts.get_context_options() posthog_headers: dict[str, str] = {} if distinct_id: @@ -236,6 +238,10 @@ def _on_before_task_publish(self, *args, **kwargs): posthog_headers[CONTEXT_SESSION_ID_HEADER] = session_id if tags: posthog_headers[CONTEXT_TAGS_HEADER] = json.dumps(tags, default=str) + if options: + posthog_headers[CONTEXT_OPTIONS_HEADER] = json.dumps( + options, default=str + ) if posthog_headers: headers.update(posthog_headers) @@ -293,6 +299,7 @@ def _on_task_prerun(self, *args, **kwargs): sender = kwargs.get("sender") request = getattr(sender, "request", None) context_tags = self._extract_propagated_tags(request) + context_options = self._extract_propagated_options(request) task_properties = self._build_task_properties( sender=sender, task_id=task_id, @@ -318,6 +325,8 @@ def _on_task_prerun(self, *args, **kwargs): merged_tags = {**context_tags, **task_properties} for key, value in merged_tags.items(): contexts.tag(key, value) + for key, value in context_options.items(): + contexts.set_context_option(key, value) if self.capture_task_lifecycle_events and self._should_track( task_name, task_properties @@ -427,14 +436,20 @@ def _apply_propagated_identity(self, request: Any) -> None: contexts.set_context_session(str(session_id)) def _extract_propagated_tags(self, request: Any) -> dict[str, Any]: + return self._extract_propagated_json(request, CONTEXT_TAGS_HEADER) + + def _extract_propagated_options(self, request: Any) -> dict[str, Any]: + return self._extract_propagated_json(request, CONTEXT_OPTIONS_HEADER) + + def _extract_propagated_json(self, request: Any, header: str) -> dict[str, Any]: headers = self._extract_headers(request) - raw_tags = headers.get(CONTEXT_TAGS_HEADER) - if not isinstance(raw_tags, (str, bytes, bytearray)): + raw = headers.get(header) + if not isinstance(raw, (str, bytes, bytearray)): return {} try: - parsed = json.loads(raw_tags) + parsed = json.loads(raw) except Exception: return {} diff --git a/posthog/mcp/README.md b/posthog/mcp/README.md index d2a0f57fc..57bbf2785 100644 --- a/posthog/mcp/README.md +++ b/posthog/mcp/README.md @@ -31,10 +31,8 @@ analytics = instrument(server, posthog) Install is just `pip install posthog`. `instrument()` needs the MCP SDK at runtime, but anyone wrapping a server already has it. -MCP analytics events report `$lib: "posthog-python-mcp"` and the installed `posthog` package version in `$lib_version`. -Request headers use the same identity and package version, so SDK Health can compare MCP traffic with Python SDK releases. -Because `$lib` is a client-level identity, `instrument()` relabels every event sent by the client passed to it. -Use a client dedicated to MCP analytics if the application also captures unrelated events. +MCP analytics events report `$lib: "posthog-python-mcp"` and the installed `posthog` package version in `$lib_version`, so SDK Health can compare MCP traffic with Python SDK releases. +The client's other events, request headers and feature flag requests keep reporting `posthog-python`, so one client can serve both. ## Versioning @@ -81,15 +79,15 @@ report none. The MCP SDK answers `initialize` itself, so the SDK observes it from outside: -- **MCP SDK 2.x**: through `Server.middleware`, on every transport. -- **MCP SDK 1.x over HTTP**: through `PostHogMcpStatelessSessionMiddleware`, which +- **MCP SDK 2.x.x**: through `Server.middleware`, on every transport. +- **MCP SDK 1.x.x over HTTP**: through `PostHogMcpStatelessSessionMiddleware`, which `instrument()` adds to the apps it autowires. If you mount the middleware yourself, pass the server: `app.add_middleware(PostHogMcpStatelessSessionMiddleware, server=mcp)`. Without it, each pod reports the session's first request as its initialize. The deprecated SSE transport also uses the session's first request. The middleware reads only requests that carry no `Mcp-Session-Id`, so an `initialize` that reuses an existing session id reports none. -- **MCP SDK 1.x over stdio**: from the session's first request. A stdio server +- **MCP SDK 1.x.x over stdio**: from the session's first request. A stdio server serves one client, so this misses only a client that never sends a request. Set `send_initialize_event=False` to stop sending `$mcp_initialize`. Many clients reconnect before @@ -105,10 +103,57 @@ instrument(server, posthog, MCPAnalyticsOptions(send_initialize_event=False)) Set `send_tools_list_event=False` to stop sending `$mcp_tools_list`. Nothing else changes: tools keep their injected arguments, and the virtual tools stay listed. -`identify` and `event_properties` run for the handshake too. On MCP SDK 1.x the +`identify` and `event_properties` run for the handshake too. On MCP SDK 1.x.x the SDK has no request context for it, so `extra["ctx"]` carries only `.request`. `get_request_headers(extra)` works the same as for any other request. +## Event options + +Set capture options, such as `cookieless_mode` or `process_person_profile`, on +MCP events with `event_options`. + +`MCPAnalyticsOptions(event_options=...)` sets options on every event +`instrument()` captures automatically, including `$exception` events. Like +`event_properties`, it is a function of `(request, extra)` that returns a dict or +`None`, and it can be sync or async: + +```python +instrument( + server, + posthog, + MCPAnalyticsOptions(event_options=lambda request, extra: {"cookieless_mode": True}), +) +``` + +The `PostHogMCP` capture methods and `McpAnalytics.capture` take an +`event_options` argument for one event: + +```python +await analytics.capture("report_exported", event_options={"cookieless_mode": True}) + +mcp_client = PostHogMCP("phc_...") +mcp_client.capture_tool_call( + "search_docs", + distinct_id="user-1", + event_options={"process_person_profile": False}, +) +``` + +`PostHogMCP.capture()` is the core client's `capture`, so it takes `options` +instead. + +An event without an identity always sends `process_person_profile: False`, even +when `event_options` sets it to `True`. An `event_options` value that is not a +dict is logged and ignored. + +`$mcp_tool_call` is captured after the tool handler returns, so options set with +`set_context_option` in a context opened inside the handler do not reach it. Use +the `event_options` callback instead. + +`before_send` sees each event's `options`. A hook that returns a new dict must +copy `options`, or the event is sent without them, including the +`process_person_profile: False` set for an event without an identity. + ## Capture safe input field names Tool-call events include `$mcp_input_keys`. The SDK records names from the @@ -150,17 +195,17 @@ Custom dispatchers can call `get_tool_input_properties()` and add its result to the `properties` argument of `capture_tool_call()`. Model capture adds an optional `llm_model` argument to compatible tool schemas. Dispatch never -enforces it, so servers keep working; strict-schema clients see the new field. Set +enforces it, so servers keep working. Strict-schema clients see the new field. Set `capture_model=False` to leave schemas untouched. Conversation correlation adds an optional `conversation_id` argument and returns a handle in -eligible tool results. Clients must echo it to group later calls; calls without it mint new handles. +eligible tool results. Clients must echo it to group later calls. Calls without it mint new handles. Set `enable_conversation_id=False` to retain transport-based session grouping and unchanged response content. Custom `PostHogMCP` dispatchers also enable model capture and conversation correlation by default. The reasoning is recorded in posthog-js `docs/adr/0013`. ## Capture the calling model -Model capture is on by default for instrumented MCP Python SDK 1.x and 2.x servers. +Model capture is on by default for instrumented MCP Python SDK 1.x.x and 2.x.x servers. The SDK records the best model identifier visible to the server as `$mcp_llm_model`. Recognized client metadata wins and sets `$mcp_llm_model_source` to `client_metadata`. The SDK also adds an `llm_model` @@ -187,18 +232,18 @@ A raw low-level server learns ownership while serving `tools/list`. A fresh inst served one has no answer, so it records `llm_model` as the self-reported model and strips nothing (posthog-js ADR-0011: reads fail open, strips fail closed). A tool that declares its own `llm_model` on such an instance is therefore recorded under `$mcp_llm_model` until a listing says -otherwise; `capture_model=False` or `before_send` are the escapes. High-level adapters and +otherwise. `capture_model=False` or `before_send` are the escapes. High-level adapters and standalone `fastmcp.FastMCP` read ownership from the registered tool schema, so they are unaffected and need no prior listing when dispatch uses that registry. -On MCP SDK 1.x, standalone FastMCP application middleware can replace or reroute a tool. +On MCP SDK 1.x.x, standalone FastMCP application middleware can replace or reroute a tool. When it overrides a listing or dispatch hook, PostHog does not inject `llm_model`: a fresh replica cannot safely distinguish that field from a replacement tool's own argument. Client metadata capture remains enabled. This also applies to pass-through logging or -authorization middleware of your own with those hooks; argument-based model capture is skipped +authorization middleware of your own with those hooks. Argument-based model capture is skipped so an application-owned value cannot be mistaken for analytics. FastMCP's stock middleware, such as `LoggingMiddleware`, `TimingMiddleware`, and `ErrorHandlingMiddleware`, never reroutes a -tool and does not count; its tool-injection middleware does. No additional catalog lookup runs +tool and does not count. Its tool-injection middleware does. No additional catalog lookup runs during a tool call. For a custom dispatcher, `PostHogMCP` enables model capture and conversation correlation @@ -266,8 +311,8 @@ Each call emits one `$mcp_feedback` event (never a `$mcp_tool_call`) with `$mcp_feedback_friction_points`, `$mcp_feedback_suggested_improvement`, `$mcp_feedback_tool`, `$mcp_feedback_sentiment`, and `$mcp_feedback_task_completed`. The summary and details also map to -`$mcp_intent`. Free-text fields are sanitized, PII-redacted, and length-bounded; -the raw arguments are never captured. An invalid `feedback_type` falls back to +`$mcp_intent`. Free-text fields are sanitized, PII-redacted, and length-bounded. +The raw arguments are never captured. An invalid `feedback_type` falls back to `other`. The agent receives an honest acknowledgement: the call records feedback and adds no tools. @@ -298,9 +343,9 @@ options = MCPAnalyticsOptions( ``` Declared extras merge into the advertised schema and are captured as -`$mcp_feedback_`. Arguments the agent invents are never captured; the +`$mcp_feedback_`. Arguments the agent invents are never captured. The handler reads them from `report.raw`. A key that collides with a core field -raises at configuration time. `on_feedback` may be sync or async; a returned +raises at configuration time. `on_feedback` may be sync or async. A returned non-blank string replaces the default reply, and a raised handler is logged and falls back to it. The event is captured either way. @@ -327,7 +372,7 @@ if call.is_feedback: return prepared.result ``` -`on_feedback` is ignored on this path — the dispatcher routes reports itself via +`on_feedback` is ignored on this path. The dispatcher routes reports itself via `call.feedback_report`. On this path you own the page rule, because you pass the switches per call. Pass @@ -359,7 +404,7 @@ tool call whenever the registry can't rule the tool out: - A raw low-level server has no registry the SDK can read. - On standalone `fastmcp.FastMCP`, middleware of your own that overrides a listing or dispatch hook can serve tools the registry lacks. -- On standalone `fastmcp.FastMCP` 3 and later, a mounted server, proxy, or +- On standalone `fastmcp.FastMCP` 3.0.0 and later, a mounted server, proxy, or other provider hides its disabled tools. ## Virtual tools on a paginated `tools/list` @@ -368,9 +413,9 @@ tool call whenever the registry can't rule the tool out: (`report_missing=True`) and `send_feedback` (`collect_feedback=True`). A client concatenates every `tools/list` page into one list, so each virtual tool -is appended to the **first page only** — the page every client reads, including +is appended to the **first page only**, the page every client reads, including clients that never follow `nextCursor`. "First page" means a request with no -cursor; an empty string is a valid opaque cursor, so `cursor: ""` is a +cursor. An empty string is a valid opaque cursor, so `cursor: ""` is a continuation page. ### Tool name collisions @@ -387,7 +432,7 @@ MCPAnalyticsOptions( - A real tool using the name **on the first page** wins: the SDK warns, injects nothing, and never intercepts yours. -- A real tool that appears **only on a later page** is shadowed — page one cannot +- A real tool that appears **only on a later page** is shadowed. Page one cannot see page two, so the SDK's tool is already advertised and calls to the name reach it. The SDK warns when that page is served. `@posthog/mcp` is the same. - Configuring **both** virtual tools with one name advertises only @@ -397,12 +442,12 @@ Warnings go to the `logger` option *and* the `posthog.mcp` standard-library logger, so a default-configured host sees them on stderr. At call time the SDK checks ownership again, covering the process that serves a -call without having served a listing — the ordinary multi-pod case. FastMCP and -v2 `MCPServer` are asked via their tool registry; a raw low-level server has +call without having served a listing, the ordinary multi-pod case. FastMCP and +the MCP SDK 2.x.x `MCPServer` are asked via their tool registry. A raw low-level server has none, so the SDK calls your own `tools/list` handler, once per call to a virtual -tool's name and never for ordinary traffic. If that check cannot answer — a +tool's name and never for ordinary traffic. If that check cannot answer (a registry lookup or a listing handler raised, or you registered `tools/list` -after `instrument()` — the call is delegated to your server rather than +after `instrument()`), the call is delegated to your server rather than intercepted, and the reason is logged: guessing the other way would swallow a real tool of yours silently. @@ -415,8 +460,8 @@ happened to be served last. A stateless MCP server issues no session id, so `$session_id` fragments across pods and the client identity (sent only at `initialize`) is lost. PostHog fixes this with -a small ASGI middleware — `PostHogMcpStatelessSessionMiddleware` — that mints a -self-encoded token onto the `Mcp-Session-Id` response header at `initialize`; the +a small ASGI middleware, `PostHogMcpStatelessSessionMiddleware`, that mints a +self-encoded token onto the `Mcp-Session-Id` response header at `initialize`. The client replays it on every request, so any pod recovers the session and harness from the header alone. @@ -424,7 +469,7 @@ the header alone. `instrument()` wraps the FastMCP server's app factories (`streamable_http_app()` / `sse_app()`), so an app you build **after** calling `instrument()` already carries the -middleware — including `mcp.run(transport="streamable-http")`, which calls those +middleware, including `mcp.run(transport="streamable-http")`, which calls those factories internally. Nothing extra to add, as long as `instrument()` runs first: ```python @@ -433,11 +478,11 @@ instrument(server, posthog) server.run(transport="streamable-http") # already wired ``` -### Manual path — required when you build the app yourself +### Manual path, required when you build the app yourself Autowiring only affects an app built **after** `instrument()` runs. If you build or -mount the ASGI app before `instrument()`, or in a different module — the common -FastAPI case — the running app gets **no** middleware and every session falls back to +mount the ASGI app before `instrument()`, or in a different module (the common +FastAPI case), the running app gets **no** middleware and every session falls back to a fragmented per-process id. Add the middleware to your app explicitly: ```python @@ -472,9 +517,9 @@ handle when this option is enabled. The failure used to be silent. It now surfaces two ways: -- **At `instrument()`** — if `streamable_http_app()` was already called before +- **At `instrument()`**: if `streamable_http_app()` was already called before `instrument()` ran, so the live app has no middleware. -- **At runtime, once** — the first time a tool call arrives over streamable HTTP and the +- **At runtime, once**: the first time a tool call arrives over streamable HTTP and the session still has to come from this process's memory. Both go to the logger you pass via `MCPAnalyticsOptions(logger=...)` **and** to the @@ -489,18 +534,18 @@ Neither fires for stdio, for a correctly-wired server, or for a conversation-anc session. The instrument-time check can't see whether you added the middleware yourself (the app is already built by then), so ignore it if you did. -Standalone `fastmcp` 4 uses the MCP SDK v2 handler registry. `instrument()` detects +Standalone `fastmcp` 4.x.x uses the MCP SDK 2.x.x handler registry. `instrument()` detects that registry automatically and captures tool calls over stdio and streamable HTTP, -including the stateless protocol. Mounted tools retain their own arguments; analytics +including the stateless protocol. Mounted tools retain their own arguments. Analytics parameters are removed before dispatch only when the tool does not declare them. Instrumenting both the wrapper and its underlying server works in either order. For versioned tools, argument ownership follows the version requested by the client. Each tool call resolves the schema through FastMCP's tool listing in the current request context, including middleware and session transforms. This adds a schema lookup per call so clients with different tool schemas cannot change how another client's arguments are handled. -The same installation code continues to support standalone FastMCP 2.x/3.x on MCP SDK v1. +The same installation code continues to support standalone FastMCP 2.x.x and 3.x.x on MCP SDK 1.x.x. -Two gaps worth knowing: jlowin's `fastmcp` 2.x/3.x doesn't expose the attribute the +Two gaps worth knowing: jlowin's `fastmcp` 2.x.x and 3.x.x don't expose the attribute the instrument-time check reads, so those servers get the runtime warning only. And the -deprecated SSE transport is excluded — it keys sessions off a query parameter, and the +deprecated SSE transport is excluded. It keys sessions off a query parameter, and the mint sets a response header an SSE client never replays, so the middleware wouldn't help it. diff --git a/posthog/mcp/__init__.py b/posthog/mcp/__init__.py index d175ae0d4..927f41be7 100644 --- a/posthog/mcp/__init__.py +++ b/posthog/mcp/__init__.py @@ -33,7 +33,7 @@ import weakref from datetime import datetime, timezone -from typing import Any, Optional +from typing import Any, Dict, Optional from posthog.client import Client @@ -151,9 +151,19 @@ class McpAnalytics: def __init__(self, key: Any) -> None: self._key = key - async def capture(self, event: str, properties: Optional[dict] = None) -> None: + async def capture( + self, + event: str, + properties: Optional[dict] = None, + *, + event_options: Optional[Dict[str, Any]] = None, + ) -> None: """Capture a custom event for this server. ``event`` is sent verbatim (a - customer-defined event, so it is not ``$``-prefixed).""" + customer-defined event, so it is not ``$``-prefixed). + + ``event_options`` sets capture options, such as + ``process_person_profile``, on the event. An event from a session + without an identity always sends ``process_person_profile: False``.""" if not isinstance(event, str) or not event: raise ValueError( 'capture() requires an event name, e.g. await analytics.capture("feedback_submitted")' @@ -169,6 +179,7 @@ async def capture(self, event: str, properties: Optional[dict] = None) -> None: "event_name": event, "timestamp": datetime.now(timezone.utc), "properties": properties, + "event_options": event_options, }, ) if coro is not None: @@ -187,7 +198,13 @@ class _NoopAnalytics(McpAnalytics): def __init__(self) -> None: # noqa: D401 - graceful degradation handle super().__init__(None) - async def capture(self, event: str, properties: Optional[dict] = None) -> None: + async def capture( + self, + event: str, + properties: Optional[dict] = None, + *, + event_options: Optional[Dict[str, Any]] = None, + ) -> None: return None async def flush(self) -> None: @@ -248,7 +265,32 @@ def instrument( :param options: Optional :class:`MCPAnalyticsOptions`. """ opts = options or MCPAnalyticsOptions() - server_build = _prepare_instrumentation(opts) + server_build = validate_server_build(opts.server_build) + + # Install the logger first so the version advisory below (and any warning) is + # actually visible rather than going to the default no-op sink. + if opts.logger: + set_logger(opts.logger) + + # The wrapping path hooks the official MCP SDK's server internals, so it needs the + # `mcp` package. It's a peer dependency (you already have it — you built the server + # with it), imported lazily here rather than bundled. PostHogMCP (custom dispatchers) + # doesn't need it at all. Raise a clear error rather than a silent no-op below. + try: + import mcp # noqa: F401 + except ImportError: + raise ModuleNotFoundError( + "instrument() needs the MCP SDK. Install it with: pip install 'mcp>=1.26'. " + "(PostHogMCP for custom dispatchers works without it.)" + ) + _warn_if_unsupported_mcp_version() + + # Fail fast on a `collect_feedback` config error (reserved extra key, + # undeclared extra_required) — before the try below, so it raises instead of + # degrading to the no-op handle and first surfacing at tools/list time. + feedback_options = resolve_collect_feedback_options(opts.collect_feedback) + if feedback_options is not None: + get_feedback_tool_descriptor(feedback_options) key = tracking_key(server) @@ -256,9 +298,15 @@ def instrument( # MCP is an optional peer: load adapters only when instrumentation is # requested, inside the no-crash boundary. Class probes stay major-specific. from ._compatibility import ( + is_fastmcp, is_fastmcp_v2, + is_low_level_server, + is_mcpserver, uses_v2_handler_registry, ) + from ._instrument_fastmcp import instrument_fastmcp + from ._instrument_lowlevel import instrument_fastmcp_v2, instrument_low_level + from ._instrument_v2 import instrument_lowlevel_v2, instrument_mcpserver_v2 from ._raised_tool_error import wrap_tool_dispatch client = _resolve_client(posthog_client) @@ -268,7 +316,13 @@ def instrument( existing_data = get_server_tracking_data(key) data = existing_data if data is None: - data = _new_tracking_data(opts, client, server_build) + sink = McpEventSink(client) if client is not None else None + data = MCPAnalyticsData( + options=opts, + sink=sink, + session_id=new_session_id(), + server_build=server_build, + ) if is_fastmcp_v2(server): wrap_tool_dispatch(server) @@ -285,12 +339,26 @@ def instrument( set_server_tracking_data(key, data) - _instrument_adapter(server, data) - - if client is not None: - from ._lib_identity import apply_mcp_lib_identity - - apply_mcp_lib_identity(client) + if is_fastmcp(server): + instrument_fastmcp(server, data) + elif is_mcpserver(server): + instrument_mcpserver_v2(server, data) + elif is_fastmcp_v2(server): + if uses_v2_handler_registry(server._mcp_server): + instrument_lowlevel_v2(server._mcp_server, data) + else: + instrument_fastmcp_v2(server, data) + elif is_low_level_server(server): + if uses_v2_handler_registry(server): + instrument_lowlevel_v2(server, data) + else: + instrument_low_level(server, data) + else: + raise TypeError( + f"Unsupported server type: {type(server)!r}. Pass a high-level server " + "(mcp.server.fastmcp.FastMCP on SDK 1.x, mcp.server.mcpserver.MCPServer " + "on SDK 2.x, or jlowin's fastmcp.FastMCP) or a low-level mcp.server.Server." + ) # Zero-config stateless minting: wrap the server's ASGI-app factories so a # stateless/multi-pod deployment keeps one $session_id + the client harness @@ -301,77 +369,3 @@ def instrument( except Exception as error: # noqa: BLE001 log(f"Warning: failed to instrument server - {error}") return _NoopAnalytics() - - -def _instrument_adapter(server: Any, data: MCPAnalyticsData) -> None: - from ._compatibility import ( - is_fastmcp, - is_fastmcp_v2, - is_low_level_server, - is_mcpserver, - uses_v2_handler_registry, - ) - from ._instrument_fastmcp import instrument_fastmcp - from ._instrument_lowlevel import instrument_fastmcp_v2, instrument_low_level - from ._instrument_v2 import instrument_lowlevel_v2, instrument_mcpserver_v2 - - if is_fastmcp(server): - instrument_fastmcp(server, data) - elif is_mcpserver(server): - instrument_mcpserver_v2(server, data) - elif is_fastmcp_v2(server): - if uses_v2_handler_registry(server._mcp_server): - instrument_lowlevel_v2(server._mcp_server, data) - else: - instrument_fastmcp_v2(server, data) - elif is_low_level_server(server): - if uses_v2_handler_registry(server): - instrument_lowlevel_v2(server, data) - else: - instrument_low_level(server, data) - else: - raise TypeError( - f"Unsupported server type: {type(server)!r}. Pass a high-level server " - "(mcp.server.fastmcp.FastMCP on SDK 1.x, mcp.server.mcpserver.MCPServer " - "on SDK 2.x, or jlowin's fastmcp.FastMCP) or a low-level mcp.server.Server." - ) - - -def _new_tracking_data( - opts: MCPAnalyticsOptions, client: Optional[Client], server_build: Optional[str] -) -> MCPAnalyticsData: - sink = McpEventSink(client) if client is not None else None - return MCPAnalyticsData( - options=opts, sink=sink, session_id=new_session_id(), server_build=server_build - ) - - -def _prepare_instrumentation(opts: MCPAnalyticsOptions) -> Optional[str]: - server_build = validate_server_build(opts.server_build) - - # Install the logger first so the version advisory below (and any warning) is - # actually visible rather than going to the default no-op sink. - if opts.logger: - set_logger(opts.logger) - - # The wrapping path hooks the official MCP SDK's server internals, so it needs the - # `mcp` package. It's a peer dependency (you already have it — you built the server - # with it), imported lazily here rather than bundled. PostHogMCP (custom dispatchers) - # doesn't need it at all. Raise a clear error rather than a silent no-op below. - try: - import mcp # noqa: F401 - except ImportError: - raise ModuleNotFoundError( - "instrument() needs the MCP SDK. Install it with: pip install 'mcp>=1.26'. " - "(PostHogMCP for custom dispatchers works without it.)" - ) - _warn_if_unsupported_mcp_version() - - # Fail fast on a `collect_feedback` config error (reserved extra key, - # undeclared extra_required) — before the try below, so it raises instead of - # degrading to the no-op handle and first surfacing at tools/list time. - feedback_options = resolve_collect_feedback_options(opts.collect_feedback) - if feedback_options is not None: - get_feedback_tool_descriptor(feedback_options) - - return server_build diff --git a/posthog/mcp/_capture.py b/posthog/mcp/_capture.py index fd2a91d84..cd5c3c098 100644 --- a/posthog/mcp/_capture.py +++ b/posthog/mcp/_capture.py @@ -71,6 +71,8 @@ def capture_event( "error_status": event_input.get("error_status"), "conversation_id": event_input.get("conversation_id"), "properties": event_input.get("properties"), + "callback_event_options": event_input.get("callback_event_options"), + "event_options": event_input.get("event_options"), } options = McpCaptureOptions( diff --git a/posthog/mcp/_instrumentation.py b/posthog/mcp/_instrumentation.py index 1a194f2f4..8c76f0efd 100644 --- a/posthog/mcp/_instrumentation.py +++ b/posthog/mcp/_instrumentation.py @@ -41,7 +41,12 @@ resolve_send_feedback_tool_name, ) from ._intent import resolve_tool_call_intent, set_event_intent -from ._internal import MCPAnalyticsData, handle_identify, resolve_event_properties +from ._internal import ( + MCPAnalyticsData, + handle_identify, + resolve_event_options, + resolve_event_properties, +) from ._tool_input import get_tool_input_properties from ._model_parameters import ( add_model_parameter_to_schema, @@ -57,12 +62,7 @@ from .session import resolve_session_id, resolve_session_id_with_source from .session_token import SessionTokenPayload, decode_session_id from .tools import resolve_missing_capability_tool_name -from .types import ( - CollectFeedbackOptions, - FeedbackReport, - InputAliasMap, - ToolInputOptions, -) +from .types import CollectFeedbackOptions, FeedbackReport, ToolInputOptions # The virtual tools this SDK advertises into tools/list. Every piece of per-tool # policy -- enable switch, configured name, warning text, warn-once @@ -290,6 +290,7 @@ def text(value: Any) -> Optional[str]: "timestamp": timestamp, } await _apply_event_properties(data, event, request, extra) + await _apply_event_options(data, event, request, extra) stamp_transport_identity(event, extra) fire_and_forget(capture_event(data, event), data) @@ -346,9 +347,9 @@ async def _maybe_emit_initialize( "protocol_version": protocol_version, "timestamp": datetime.now(timezone.utc), } - await _apply_event_properties( - data, event, {"method": "initialize", "params": {}}, extra - ) + request = {"method": "initialize", "params": {}} + await _apply_event_properties(data, event, request, extra) + await _apply_event_options(data, event, request, extra) stamp_transport_identity(event, extra) fire_and_forget(capture_event(data, event), data) @@ -366,6 +367,19 @@ async def _apply_event_properties( event["properties"] = props +async def _apply_event_options( + data: MCPAnalyticsData, + event: Dict[str, Any], + request: Dict[str, Any], + extra: Optional[Dict[str, Any]], +) -> None: + """Resolve the customer's ``event_options`` callback onto the event, for the + same events as ``event_properties``.""" + options = await resolve_event_options(data, request, extra) + if options is not None: + event["callback_event_options"] = options + + def resolve_session_and_client( raw_session_id: Optional[str], client_name: Optional[str], @@ -824,10 +838,23 @@ async def record_tool_call( event["llm_model"] = model event["llm_model_source"] = source - _set_tool_outcome(event, result, error) + if result is not None: + event["response"] = _wrap_response(result) + if error is None and is_tool_result_error(result): + error = result + if error is not None: + event["is_error"] = True + event["error"] = capture_exception(error) + event["error_status"] = http_status(error) props = await resolve_event_properties(data, request, extra) - input_aliases = _resolve_input_aliases(data, name) + await _apply_event_options(data, event, request, extra) + input_aliases = None + if data.options.resolve_input_aliases is not None: + try: + input_aliases = data.options.resolve_input_aliases(name) + except Exception as err: # noqa: BLE001 - analytics callbacks are isolated + log(f"Warning: resolve_input_aliases failed for tool {name}: {err}") event["properties"] = { **(props or {}), **get_tool_input_properties( @@ -1032,7 +1059,18 @@ def resolve_virtual_tool_injection( listed = advertised_tool_names(tools) if not is_first_page: - _warn_shadowed_virtual_tools(data, enabled, listed) + for kind, name in enabled.items(): + # Only warn about a tool we actually shadowed. If this kind never + # made it onto the first page -- a real tool already held the name + # ("blocked"), or the other virtual tool won it ("duplicate") -- + # then nothing of ours is advertised under it and the host's tool + # runs untouched. Telling them otherwise sends them chasing a bug + # that isn't there. + if name in listed and not any( + (kind, name, variant) in data.warned_virtual_tool_collisions + for variant in ("blocked", "duplicate") + ): + _warn_virtual_tool_collision(data, kind, name, "shadowed") return {} injectable: Dict[str, str] = {} @@ -1203,7 +1241,11 @@ def mutate_tool_schema( schema, "conversation_id" ): schema = add_conversation_id_to_schema(schema, tool.name) - _write_tool_schema(tool, schema_attribute, original_schema, schema) + if schema is not original_schema: + try: + setattr(tool, schema_attribute, schema) + except Exception: # noqa: BLE001 - some schema attrs may be read-only + log(f"WARN: could not set {schema_attribute} on tool {tool.name}") if data.options.enable_conversation_id: data.tool_output_instructions[tool.name] = add_instructions_to_output_schema( tool @@ -1378,6 +1420,7 @@ async def record_missing_capability( event["llm_model"] = model event["llm_model_source"] = source await _apply_event_properties(data, event, request, extra) + await _apply_event_options(data, event, request, extra) stamp_transport_identity(event, extra) fire_and_forget(capture_event(data, event), data) except Exception as err: # noqa: BLE001 - isolate analytics from the tool path @@ -1466,6 +1509,7 @@ async def record_feedback( **(props or {}), **build_feedback_event_properties(report), } + await _apply_event_options(data, event, request, extra) stamp_transport_identity(event, extra) fire_and_forget(capture_event(data, event), data) except Exception as err: # noqa: BLE001 - isolate analytics from the tool path @@ -1506,6 +1550,7 @@ async def record_tools_list( if error is not None: event["error"] = capture_exception(error) await _apply_event_properties(data, event, request, extra) + await _apply_event_options(data, event, request, extra) stamp_transport_identity(event, extra) fire_and_forget(capture_event(data, event), data) except Exception as err: # noqa: BLE001 - isolate analytics from the tool path @@ -1558,57 +1603,8 @@ async def record_resource_request( if error is not None: event["error"] = capture_exception(error) await _apply_event_properties(data, event, request, extra) + await _apply_event_options(data, event, request, extra) stamp_transport_identity(event, extra) fire_and_forget(capture_event(data, event), data) except Exception as err: # noqa: BLE001 - isolate analytics from the request path log(f"record_resource_request failed (event dropped): {err}") - - -def _set_tool_outcome(event: Dict[str, Any], result: Any, error: Any) -> None: - if result is not None: - event["response"] = _wrap_response(result) - if error is None and is_tool_result_error(result): - error = result - if error is not None: - event["is_error"] = True - event["error"] = capture_exception(error) - event["error_status"] = http_status(error) - - -def _resolve_input_aliases( - data: MCPAnalyticsData, name: str -) -> Optional[InputAliasMap]: - input_aliases = None - if data.options.resolve_input_aliases is not None: - try: - input_aliases = data.options.resolve_input_aliases(name) - except Exception as err: # noqa: BLE001 - analytics callbacks are isolated - log(f"Warning: resolve_input_aliases failed for tool {name}: {err}") - return input_aliases - - -def _warn_shadowed_virtual_tools( - data: MCPAnalyticsData, enabled: Dict[str, str], listed: Set[str] -) -> None: - for kind, name in enabled.items(): - # Only warn about a tool we actually shadowed. If this kind never - # made it onto the first page -- a real tool already held the name - # ("blocked"), or the other virtual tool won it ("duplicate") -- - # then nothing of ours is advertised under it and the host's tool - # runs untouched. Telling them otherwise sends them chasing a bug - # that isn't there. - if name in listed and not any( - (kind, name, variant) in data.warned_virtual_tool_collisions - for variant in ("blocked", "duplicate") - ): - _warn_virtual_tool_collision(data, kind, name, "shadowed") - - -def _write_tool_schema( - tool: Any, schema_attribute: str, original_schema: Any, schema: Any -) -> None: - if schema is not original_schema: - try: - setattr(tool, schema_attribute, schema) - except Exception: # noqa: BLE001 - some schema attrs may be read-only - log(f"WARN: could not set {schema_attribute} on tool {tool.name}") diff --git a/posthog/mcp/_internal.py b/posthog/mcp/_internal.py index 44a1eeb48..fdbcf3688 100644 --- a/posthog/mcp/_internal.py +++ b/posthog/mcp/_internal.py @@ -221,3 +221,19 @@ async def resolve_event_properties( except Exception as e: # noqa: BLE001 log(f"event_properties callback error: {e}") return None + + +async def resolve_event_options( + data: MCPAnalyticsData, + request: Dict[str, Any], + extra: Optional[Dict[str, Any]] = None, +) -> Any: + """Return the ``event_options`` callback's result as given. The event + builder checks that it is a dict, as it does for per-call options.""" + if not data.options.event_options: + return None + try: + return await _maybe_await(data.options.event_options(request, extra)) + except Exception as e: # noqa: BLE001 + log(f"event_options callback error: {e}") + return None diff --git a/posthog/mcp/_lib_identity.py b/posthog/mcp/_lib_identity.py deleted file mode 100644 index 02bb11e57..000000000 --- a/posthog/mcp/_lib_identity.py +++ /dev/null @@ -1,15 +0,0 @@ -"""Apply the MCP-specific identity to the underlying PostHog client.""" - -from __future__ import annotations - -from ..client import Client -from ..version import VERSION - -from .constants import POSTHOG_MCP_LIB_NAME - - -def apply_mcp_lib_identity(client: Client) -> None: - """Relabel every event sent by ``client`` as coming from ``posthog.mcp``.""" - set_identity = getattr(client, "_set_library_identity", None) - if set_identity is not None: - set_identity(POSTHOG_MCP_LIB_NAME, VERSION) diff --git a/posthog/mcp/_posthog_events.py b/posthog/mcp/_posthog_events.py index 4f64a2de0..45b1d4c02 100644 --- a/posthog/mcp/_posthog_events.py +++ b/posthog/mcp/_posthog_events.py @@ -10,12 +10,17 @@ from datetime import datetime, timezone from typing import Any, Dict, List +from posthog.capture_event import _fill_library, _merge_groups +from posthog.version import VERSION + from .constants import ( POSTHOG_MCP_ANALYTICS_SOURCE, + POSTHOG_MCP_LIB_NAME, PostHogMCPAnalyticsEvent, PostHogMCPAnalyticsProperty, ) from ._event_types import MCPAnalyticsEventType +from .logger import warn from .types import Event, PostHogCaptureEvent _BUILT_IN_EVENT_NAME_BY_TYPE = { @@ -48,27 +53,29 @@ def _get_timestamp(event: Event) -> datetime: def build_posthog_capture_events( event: Event, enable_exception_autocapture: bool = True ) -> List[PostHogCaptureEvent]: - batch = [_build_capture_event(event)] + options = _get_options(event) + batch = [_build_capture_event(event, dict(options))] if ( event.get("is_error") and event.get("error") and enable_exception_autocapture is not False ): - batch.append(_build_exception_event(event)) + batch.append(_build_exception_event(event, dict(options))) + for capture in batch: + _fill_library(capture["properties"], (POSTHOG_MCP_LIB_NAME, VERSION), None) return batch -def _build_capture_event(event: Event) -> PostHogCaptureEvent: +def _build_capture_event(event: Event, options: Dict[str, Any]) -> PostHogCaptureEvent: properties: Dict[str, Any] = { _P.INTERFACE: "mcp", _P.SOURCE: POSTHOG_MCP_ANALYTICS_SOURCE, } _add_session_id(event, properties) _add_conversation_id(event, properties) - _add_person_processing(event, properties) - _add_groups(event, properties) _add_common_properties(event, properties) _add_custom_properties(event, properties) + _add_groups(event, properties) _add_server_build(event, properties) event_name = ( @@ -78,6 +85,7 @@ def _build_capture_event(event: Event) -> PostHogCaptureEvent: "event": event_name, "distinct_id": _get_distinct_id(event), "properties": properties, + "options": options, "timestamp": _get_timestamp(event), } @@ -95,16 +103,40 @@ def _add_conversation_id(event: Event, properties: Dict[str, Any]) -> None: def _add_groups(event: Event, properties: Dict[str, Any]) -> None: + """Merge the typed groups over a custom ``$groups`` property, key by key.""" groups = event.get("groups") if groups: - properties["$groups"] = groups + _merge_groups(properties, groups) + + +def _event_options(value: Any, source: str) -> Dict[str, Any]: + """Return a copy of caller options, or ``{}`` when they are not a dict.""" + if value is None: + return {} + if not isinstance(value, dict): + warn( + f"{source} must be a dict, got {type(value).__name__}. " + "Sending the event without them." + ) + return {} + return dict(value) -def _add_person_processing(event: Event, properties: Dict[str, Any]) -> None: +def _get_options(event: Event) -> Dict[str, Any]: + # Per-call options win over the callback's, key by key. + options = { + **_event_options( + event.get("callback_event_options"), "The event_options callback result" + ), + **_event_options(event.get("event_options"), "event_options"), + } # Without a resolved identity the distinct id is just the session id, so # processing a person profile would mint one anonymous person per session. + # Applied last, so it beats caller options and any custom + # $process_person_profile property. if not event.get("identify_actor_given_id"): - properties["$process_person_profile"] = False + options["process_person_profile"] = False + return options def _is_tool_call(event: Event) -> bool: @@ -245,12 +277,12 @@ def _add_server_build(event: Event, properties: Dict[str, Any]) -> None: properties[_P.SERVER_BUILD] = event["server_build"] -def _build_exception_event(event: Event) -> PostHogCaptureEvent: +def _build_exception_event( + event: Event, options: Dict[str, Any] +) -> PostHogCaptureEvent: properties: Dict[str, Any] = {_P.INTERFACE: "mcp"} _add_session_id(event, properties) _add_conversation_id(event, properties) - _add_person_processing(event, properties) - _add_groups(event, properties) error = event.get("error") if error: @@ -279,12 +311,14 @@ def _build_exception_event(event: Event) -> PostHogCaptureEvent: ) _add_custom_properties(event, properties) + _add_groups(event, properties) _add_server_build(event, properties) return { "event": PostHogMCPAnalyticsEvent.EXCEPTION, "distinct_id": _get_distinct_id(event), "properties": properties, + "options": options, "timestamp": _get_timestamp(event), } diff --git a/posthog/mcp/_sink.py b/posthog/mcp/_sink.py index 7d1db967f..15a5e789a 100644 --- a/posthog/mcp/_sink.py +++ b/posthog/mcp/_sink.py @@ -106,6 +106,7 @@ async def capture(self, event: McpEvent, options: McpCaptureOptions) -> None: capture_event["event"], distinct_id=capture_event["distinct_id"], properties=capture_event["properties"], + options=capture_event.get("options"), timestamp=capture_event.get("timestamp"), uuid=_uuid7(), ) diff --git a/posthog/mcp/posthog_mcp.py b/posthog/mcp/posthog_mcp.py index f176e93de..46896fed1 100644 --- a/posthog/mcp/posthog_mcp.py +++ b/posthog/mcp/posthog_mcp.py @@ -42,7 +42,6 @@ fire_and_forget, virtual_tool_collision_message, ) -from ._lib_identity import apply_mcp_lib_identity from .logger import log, warn from ._model_parameters import ( add_model_parameter_to_schema, @@ -122,7 +121,6 @@ def __init__( ) -> None: self._server_build = validate_server_build(server_build) super().__init__(api_key, **kwargs) - apply_mcp_lib_identity(self) self._mcp_sink = McpEventSink(self) self._missing_capability_tool_name = ( missing_capability_tool_name or _GET_MORE_TOOLS_NAME @@ -177,7 +175,10 @@ def shutdown(self) -> None: def capture( self, event: str, **kwargs: Unpack[OptionalCaptureArgs] ) -> Optional[str]: - """Capture a custom event with the configured server build as a default.""" + """Capture a custom event with the configured server build as a default. + + This is the core ``Client.capture``, so it takes ``options=``. The MCP + ``capture_*`` methods take ``event_options=`` instead.""" if self._server_build is not None: properties = dict(kwargs.get("properties") or {}) if properties.get(PostHogMCPAnalyticsProperty.SERVER_BUILD) is None: @@ -212,9 +213,14 @@ def capture_tool_call( set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, + event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None, ) -> None: - """Capture a tool invocation. Emits ``$mcp_tool_call`` (+ ``$exception`` on error).""" + """Capture a tool invocation. Emits ``$mcp_tool_call`` (+ ``$exception`` on error). + + ``event_options`` sets capture options, such as + ``process_person_profile``, on the event. Without ``distinct_id`` the + event always sends ``process_person_profile: False``.""" event = self._base_event( MCPAnalyticsEventType.MCP_TOOLS_CALL, distinct_id, @@ -223,6 +229,7 @@ def capture_tool_call( set_properties, groups, properties, + event_options, timestamp, client_user_agent, vendor_client, @@ -261,9 +268,14 @@ def capture_initialize( set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, + event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None, ) -> None: - """Capture the connection handshake. Emits ``$mcp_initialize``.""" + """Capture the connection handshake. Emits ``$mcp_initialize``. + + ``event_options`` sets capture options, such as + ``process_person_profile``, on the event. Without ``distinct_id`` the + event always sends ``process_person_profile: False``.""" event = self._base_event( MCPAnalyticsEventType.MCP_INITIALIZE, distinct_id, @@ -272,6 +284,7 @@ def capture_initialize( set_properties, groups, properties, + event_options, timestamp, client_user_agent, vendor_client, @@ -302,10 +315,15 @@ def capture_tools_list( set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, + event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None, ) -> None: """Capture a ``tools/list`` response. Emits ``$mcp_tools_list`` with the - advertised tool names (``$mcp_listed_tool_names``).""" + advertised tool names (``$mcp_listed_tool_names``). + + ``event_options`` sets capture options, such as + ``process_person_profile``, on the event. Without ``distinct_id`` the + event always sends ``process_person_profile: False``.""" event = self._base_event( MCPAnalyticsEventType.MCP_TOOLS_LIST, distinct_id, @@ -314,6 +332,7 @@ def capture_tools_list( set_properties, groups, properties, + event_options, timestamp, client_user_agent, vendor_client, @@ -347,12 +366,17 @@ def capture_missing_capability( set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, + event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None, ) -> None: """Capture a ``get_more_tools`` call as a missing-capability report. Emits ``$mcp_missing_capability`` with the agent's description as ``$mcp_intent``. Reply to the agent with ``get_more_tools_result()`` after passing it - through :meth:`prepare_tool_result`.""" + through :meth:`prepare_tool_result`. + + ``event_options`` sets capture options, such as + ``process_person_profile``, on the event. Without ``distinct_id`` the + event always sends ``process_person_profile: False``.""" event = self._base_event( MCPAnalyticsEventType.MCP_MISSING_CAPABILITY, distinct_id, @@ -361,6 +385,7 @@ def capture_missing_capability( set_properties, groups, properties, + event_options, timestamp, client_user_agent, vendor_client, @@ -387,6 +412,7 @@ def capture_feedback( set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, + event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None, ) -> None: """Capture a ``send_feedback`` call as an agent-feedback report. Emits @@ -394,7 +420,11 @@ def capture_feedback( summary/details as ``$mcp_intent``. Reply to the agent with ``send_feedback_result()`` (or a custom text) after routing the report to your own feedback backend and passing the reply through - :meth:`prepare_tool_result`.""" + :meth:`prepare_tool_result`. + + ``event_options`` sets capture options, such as + ``process_person_profile``, on the event. Without ``distinct_id`` the + event always sends ``process_person_profile: False``.""" event = self._base_event( MCPAnalyticsEventType.MCP_FEEDBACK, distinct_id, @@ -403,6 +433,7 @@ def capture_feedback( set_properties, groups, properties, + event_options, timestamp, client_user_agent, vendor_client, @@ -756,6 +787,7 @@ def _base_event( set_properties: Optional[JsonRecord], groups: Optional[Dict[str, str]], properties: Optional[JsonRecord], + event_options: Optional[Dict[str, Any]], timestamp: Optional[datetime], client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, @@ -766,6 +798,7 @@ def _base_event( "conversation_id": conversation_id, "timestamp": timestamp or datetime.now(timezone.utc), "properties": properties, + "event_options": event_options, "groups": groups, # Raw transport headers. A custom dispatcher holds its own request # object, so it passes these itself; instrumented servers read them diff --git a/posthog/mcp/types.py b/posthog/mcp/types.py index a44f23ab2..e4aee8d83 100644 --- a/posthog/mcp/types.py +++ b/posthog/mcp/types.py @@ -62,8 +62,9 @@ # Internal MCP event as it flows through the SDK before capture. Modeled as a # plain dict (constructed and read with ``.get()`` throughout) to mirror the TS # plain-object pipeline. Snake_case keys map to the ``$mcp_*`` wire keys in -# ``posthog_events``. Known keys: client_name, client_version, conversation_id, -# duration, error, error_status, error_type, event_name, event_type, groups, id, identify_actor_data, +# ``posthog_events``. Known keys: callback_event_options, client_name, +# client_version, conversation_id, duration, error, error_status, error_type, +# event_name, event_options, event_type, groups, id, identify_actor_data, # identify_actor_given_id, is_error, listed_tool_names, parameters, properties, # resource_name, response, server_name, server_version, session_id, timestamp, # tool_category, tool_description, user_intent, user_intent_source, llm_model, @@ -78,6 +79,7 @@ class PostHogCaptureEvent(TypedDict, total=False): distinct_id: str event: str properties: Dict[str, Any] + options: Dict[str, Any] timestamp: datetime @@ -179,6 +181,7 @@ class FeedbackReport: ] # (request, extra) -> Optional[UserIdentity] | awaitable IntentFallbackFn = Callable[..., Any] # (request, extra) -> Optional[str] | awaitable EventPropertiesFn = Callable[..., Any] # (request, extra) -> Optional[dict] | awaitable +EventOptionsFn = Callable[..., Any] # (request, extra) -> Optional[dict] | awaitable InputAliasMap = Dict[str, List[str]] @@ -253,6 +256,11 @@ class MCPAnalyticsOptions: # no `$mcp_tools_list`. Nothing else changes: tools keep their injected # arguments, and the virtual tools stay listed. send_tools_list_event: bool = True + # Capture options, such as `process_person_profile`, for every + # auto-captured event: a callable (request, extra) -> dict | None, sync or + # async, called for the same events as `event_properties`. An event without + # an identity always sends `process_person_profile: False`. + event_options: Optional[EventOptionsFn] = None @dataclass diff --git a/posthog/request.py b/posthog/request.py index e7f179374..4703d6ec9 100644 --- a/posthog/request.py +++ b/posthog/request.py @@ -4,11 +4,8 @@ import re import socket import time -import zlib from dataclasses import dataclass from datetime import date, datetime, timezone -from gzip import GzipFile -from io import BytesIO from typing import Any, List, Optional, Tuple, Union, cast from uuid import UUID @@ -78,7 +75,7 @@ def init_poolmanager(self, *args, **kwargs): def _build_session(socket_options: Optional[SocketOptions] = None) -> requests.Session: - """Build a session for general requests (batch, remote config, etc.).""" + """Build a session for general requests (remote config, flag definitions, etc.).""" adapter = HTTPAdapterWithSocketOptions( max_retries=Retry( total=2, @@ -92,13 +89,13 @@ def _build_session(socket_options: Optional[SocketOptions] = None) -> requests.S return session -def _build_flags_session( +def _build_no_retry_session( socket_options: Optional[SocketOptions] = None, ) -> requests.Session: - """Build a session for feature flag requests. + """Build a session whose adapter never retries; ``flags()`` and capture own retries. - /flags retries are handled explicitly in ``flags()`` so that only - transport failures and contract-defined transient HTTP responses are retried. + Capture needs a fresh ``PostHog-Request-Timestamp`` on every physical attempt, + because capture uses it to correct clock skew. """ adapter = HTTPAdapterWithSocketOptions( max_retries=Retry(total=0, connect=0, read=0, status=0), @@ -110,7 +107,8 @@ def _build_flags_session( _session = _build_session() -_flags_session = _build_flags_session() +_flags_session = _build_no_retry_session() +_capture_session = _build_no_retry_session() _socket_options: Optional[SocketOptions] = None _pooling_enabled = True @@ -124,7 +122,13 @@ def _get_session() -> requests.Session: def _get_flags_session() -> requests.Session: if _pooling_enabled: return _flags_session - return _build_flags_session(_socket_options) + return _build_no_retry_session(_socket_options) + + +def _get_capture_session() -> requests.Session: + if _pooling_enabled: + return _capture_session + return _build_no_retry_session(_socket_options) def reset_sessions() -> None: @@ -132,13 +136,16 @@ def reset_sessions() -> None: Reset the global sessions. This should be called after a fork to ensure that the child process does not use the parent's connection pool. """ - global _session, _flags_session + global _session, _flags_session, _capture_session if _session: _session.close() if _flags_session: _flags_session.close() + if _capture_session: + _capture_session.close() _session = _build_session(_socket_options) - _flags_session = _build_flags_session(_socket_options) + _flags_session = _build_no_retry_session(_socket_options) + _capture_session = _build_no_retry_session(_socket_options) def set_socket_options(socket_options: Optional[SocketOptions]) -> None: @@ -156,12 +163,13 @@ def set_socket_options(socket_options: Optional[SocketOptions]) -> None: from posthog import set_socket_options set_socket_options([(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)]) """ - global _session, _flags_session, _socket_options + global _session, _flags_session, _capture_session, _socket_options if socket_options == _socket_options: return _socket_options = socket_options _session = _build_session(socket_options) - _flags_session = _build_flags_session(socket_options) + _flags_session = _build_no_retry_session(socket_options) + _capture_session = _build_no_retry_session(socket_options) def enable_keep_alive() -> None: @@ -170,6 +178,9 @@ def enable_keep_alive() -> None: This helps prevent idle pooled connections from being dropped by network infrastructure. Call during initialization, before making API requests. + Where the platform supports the corresponding socket options, it uses + a 60 second idle time, a 60 second probe interval and 3 probes before + timeout. Unsupported settings keep their system defaults. """ set_socket_options(KEEP_ALIVE_SOCKET_OPTIONS) @@ -232,38 +243,26 @@ def post( api_key: str, host: Optional[str] = None, path: Optional[str] = None, - gzip: bool = False, + *, timeout: float = 15, session: Optional[requests.Session] = None, **kwargs, ) -> requests.Response: """Post the `kwargs` to the API""" log = logging.getLogger("posthog") - user_agent = kwargs.pop("_user_agent", USER_AGENT) body = kwargs body["sent_at"] = datetime.now(tz=timezone.utc).isoformat() trimmed_host = remove_trailing_slash(normalize_host(host)) url = trimmed_host + cast(str, path) body["api_key"] = api_key - data: str | bytes = json.dumps(body, cls=DatetimeSerializer) + data = json.dumps(body, cls=DatetimeSerializer) if log.isEnabledFor(logging.DEBUG): log.debug( "making request: %s to url: %s", json.dumps({**body, "api_key": "[redacted]"}, cls=DatetimeSerializer), url, ) - headers = {"Content-Type": "application/json", "User-Agent": user_agent} - if gzip: - try: - buf = BytesIO() - with GzipFile(fileobj=buf, mode="w") as gz: - # 'data' was produced by json.dumps(), - # whose default encoding is utf-8. - gz.write(cast(str, data).encode("utf-8")) - data = buf.getvalue() - headers["Content-Encoding"] = "gzip" - except (OSError, zlib.error) as exc: - log.warning("failed to gzip request body, sending uncompressed: %s", exc) + headers = {"Content-Type": "application/json", "User-Agent": USER_AGENT} res = (session or _get_session()).post( url, data=data, headers=headers, timeout=timeout @@ -336,13 +335,12 @@ def _feature_flags_retry_delay(failed_attempt: int) -> float: def flags( api_key: str, host: Optional[str] = None, - gzip: bool = False, + *, timeout: float = 15, max_retries: int = 1, **kwargs, ) -> Any: """Post the kwargs to the flags API endpoint with bounded transient retries.""" - user_agent = kwargs.pop("_user_agent", USER_AGENT) retries = max(0, max_retries) failed_attempt = 0 @@ -352,10 +350,8 @@ def flags( api_key, host, "/flags/?v=4", - gzip, - timeout, + timeout=timeout, session=_get_flags_session(), - _user_agent=user_agent, **kwargs, ) return _process_response( @@ -386,47 +382,15 @@ def remote_config( timeout: float = 15, ) -> Any: """Get remote config flag value from remote_config API endpoint""" - return _remote_config(personal_api_key, project_api_key, host, key, timeout) - - -def _remote_config( - personal_api_key: str, - project_api_key: str, - host: Optional[str] = None, - key: str = "", - timeout: float = 15, - *, - _user_agent: str = USER_AGENT, -) -> Any: - response = _get( + response = get( personal_api_key, f"/api/projects/@current/feature_flags/{key}/remote_config?token={project_api_key}", host, timeout, - _user_agent=_user_agent, ) return response.data -EVENTS_ENDPOINT = "/batch/" -AI_EVENTS_ENDPOINT = "/i/v0/ai/batch/" - - -def batch_post( - api_key: str, - host: Optional[str] = None, - gzip: bool = False, - timeout: float = 15, - path: str = EVENTS_ENDPOINT, - **kwargs, -) -> requests.Response: - """Post the `kwargs` to the batch API endpoint for events""" - res = post(api_key, host, path, gzip, timeout, **kwargs) - return _process_response( - res, success_message="data uploaded successfully", return_json=False - ) - - def get( api_key: str, url: str, @@ -441,25 +405,10 @@ def get( - not_modified=True and data=None if server returns 304 - not_modified=False and data=response if server returns 200 """ - return _get(api_key, url, host, timeout, etag) - - -def _get( - api_key: str, - url: str, - host: Optional[str] = None, - timeout: Optional[float] = None, - etag: Optional[str] = None, - *, - _user_agent: str = USER_AGENT, -) -> GetResponse: log = logging.getLogger("posthog") trimmed_host = remove_trailing_slash(normalize_host(host)) full_url = trimmed_host + url - headers = { - "Authorization": "Bearer %s" % api_key, - "User-Agent": _user_agent, - } + headers = {"Authorization": "Bearer %s" % api_key, "User-Agent": USER_AGENT} if etag: headers["If-None-Match"] = etag @@ -532,6 +481,12 @@ def default(self, obj: Any): return json.JSONEncoder.default(self, obj) def encode(self, o: Any) -> str: + # A strict encode fails only on a non-finite float, so finite events skip the copy. + if not self.allow_nan: + try: + return super().encode(o) + except ValueError: + pass return super().encode(_replace_non_finite_floats(o)) diff --git a/posthog/test/ai/anthropic/test_anthropic.py b/posthog/test/ai/anthropic/test_anthropic.py index 22e8d1767..1bdb0051d 100644 --- a/posthog/test/ai/anthropic/test_anthropic.py +++ b/posthog/test/ai/anthropic/test_anthropic.py @@ -29,7 +29,12 @@ from anthropic.types.raw_message_delta_event import Delta from posthog.ai.anthropic import Anthropic, AnthropicBedrock, AsyncAnthropic - from posthog.test.ai.utils import RecordingAsyncStream + from posthog.test.ai.utils import ( + POSTHOG_OPTIONS_CASES, + RecordingAsyncStream, + assert_captured_options, + posthog_call_kwargs, + ) ANTHROPIC_AVAILABLE = True except ImportError: @@ -430,9 +435,9 @@ def test_basic_completion(mock_client, mock_anthropic_response): ) assert response == mock_anthropic_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -476,7 +481,7 @@ def test_tokens_source_passthrough(mock_client, mock_anthropic_response): posthog_properties={"$ai_input_tokens": 99999}, ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_tokens_source"] == "passthrough" assert props["$ai_input_tokens"] == 99999 @@ -494,9 +499,9 @@ def test_groups(mock_client, mock_anthropic_response): ) assert response == mock_anthropic_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] assert call_args["groups"] == {"company": "test_company"} @@ -513,9 +518,9 @@ def test_privacy_mode_local(mock_client, mock_anthropic_response): ) assert response == mock_anthropic_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] is None assert props["$ai_output_choices"] is None @@ -535,9 +540,9 @@ def test_privacy_mode_global(mock_client, mock_anthropic_response): ) assert response == mock_anthropic_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] is None assert props["$ai_output_choices"] is None @@ -561,9 +566,9 @@ def test_basic_integration(mock_client): system="You must always answer with 'Bar'.", ) - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" assert call_args["event"] == "$ai_generation" @@ -607,9 +612,9 @@ async def mock_async_create(**kwargs): posthog_properties={"foo": "bar"}, ) - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -669,9 +674,9 @@ async def async_create_wrapper(**kwargs): [c async for c in response] # Capture happens in the async finally block before generator completes - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] == [ @@ -691,9 +696,9 @@ def test_error(mock_client, mock_anthropic_response): messages=[{"role": "user", "content": "Hello"}], ) - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_is_error"] is True assert props["$ai_error"] == "Test error" @@ -713,9 +718,9 @@ def test_cached_tokens(mock_client, mock_anthropic_response_with_cached_tokens): ) assert response == mock_anthropic_response_with_cached_tokens - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -754,7 +759,7 @@ def test_preserves_cache_creation_ttl_breakdown_non_streaming( ) assert_cache_creation_ttl_breakdown_preserved( - mock_client.capture.call_args.kwargs["properties"] + mock_client.capture_ai.call_args.kwargs["properties"] ) @@ -776,7 +781,7 @@ async def mock_async_create(**kwargs): ) assert_cache_creation_ttl_breakdown_preserved( - mock_client.capture.call_args.kwargs["properties"] + mock_client.capture_ai.call_args.kwargs["properties"] ) @@ -794,7 +799,7 @@ def test_preserves_cache_creation_ttl_breakdown_streaming(mock_client): list(response) assert_cache_creation_ttl_breakdown_preserved( - mock_client.capture.call_args.kwargs["properties"] + mock_client.capture_ai.call_args.kwargs["properties"] ) @@ -820,7 +825,7 @@ async def mock_async_create(**kwargs): [event async for event in response] assert_cache_creation_ttl_breakdown_preserved( - mock_client.capture.call_args.kwargs["properties"] + mock_client.capture_ai.call_args.kwargs["properties"] ) @@ -880,7 +885,7 @@ def test_streaming_takes_cumulative_message_delta_usage(mock_client): ) list(response) - assert_cumulative_delta_usage(mock_client.capture.call_args.kwargs["properties"]) + assert_cumulative_delta_usage(mock_client.capture_ai.call_args.kwargs["properties"]) @pytest.mark.asyncio @@ -904,7 +909,7 @@ async def mock_async_create(**kwargs): ) [event async for event in response] - assert_cumulative_delta_usage(mock_client.capture.call_args.kwargs["properties"]) + assert_cumulative_delta_usage(mock_client.capture_ai.call_args.kwargs["properties"]) def anthropic_stream_with_thinking_tokens(): @@ -939,7 +944,7 @@ def test_streaming_reports_thinking_tokens_as_reasoning_tokens(mock_client): ) list(response) - props = mock_client.capture.call_args.kwargs["properties"] + props = mock_client.capture_ai.call_args.kwargs["properties"] assert props["$ai_output_tokens"] == 110 assert props["$ai_reasoning_tokens"] == 40 @@ -967,7 +972,7 @@ async def mock_async_create(**kwargs): ) [event async for event in response] - props = mock_client.capture.call_args.kwargs["properties"] + props = mock_client.capture_ai.call_args.kwargs["properties"] assert props["$ai_reasoning_tokens"] == 40 @@ -1021,7 +1026,7 @@ def test_streaming_multiple_message_deltas_do_not_stack_output_tokens(mock_clien ) list(response) - props = mock_client.capture.call_args.kwargs["properties"] + props = mock_client.capture_ai.call_args.kwargs["properties"] assert props["$ai_output_tokens"] == 110 @@ -1048,7 +1053,7 @@ async def mock_async_create(**kwargs): ) [event async for event in response] - props = mock_client.capture.call_args.kwargs["properties"] + props = mock_client.capture_ai.call_args.kwargs["properties"] assert props["$ai_output_tokens"] == 110 @@ -1071,7 +1076,7 @@ def test_anthropic_bedrock_preserves_cache_creation_ttl_breakdown( ) assert_cache_creation_ttl_breakdown_preserved( - mock_client.capture.call_args.kwargs["properties"] + mock_client.capture_ai.call_args.kwargs["properties"] ) @@ -1110,9 +1115,9 @@ def test_tool_definition(mock_client, mock_anthropic_response): ) assert response == mock_anthropic_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -1164,9 +1169,9 @@ def test_tool_calls_in_output_choices( ) assert response == mock_anthropic_response_with_tool_calls - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -1227,9 +1232,9 @@ def test_tool_calls_only_no_content( ) assert response == mock_anthropic_response_tool_calls_only - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -1296,9 +1301,9 @@ async def run_test(): response = asyncio.run(run_test()) assert response == mock_anthropic_response_with_tool_calls - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -1364,9 +1369,9 @@ def test_streaming_with_tool_calls(mock_client, mock_anthropic_stream_with_tools list(response) # Capture happens synchronously when generator is exhausted - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -1506,7 +1511,7 @@ def stream_generator(): ) list(response) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_output_choices"] == [ { "role": "assistant", @@ -1573,9 +1578,9 @@ async def run_test(): asyncio.run(run_test()) # Capture completes before asyncio.run() returns - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -1655,9 +1660,9 @@ def test_streaming_with_thinking(mock_client, mock_anthropic_stream_with_thinkin # Consume the stream - this triggers the finally block synchronously list(response) - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] output_choices = props["$ai_output_choices"] @@ -1707,9 +1712,9 @@ async def run_test(): asyncio.run(run_test()) - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] output_choices = props["$ai_output_choices"] @@ -1761,9 +1766,9 @@ def __init__(self): ) assert response == mock_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify web search count is captured @@ -1843,9 +1848,9 @@ def test_streaming_with_web_search(mock_client, mock_anthropic_stream_with_web_s list(response) # Capture happens synchronously when generator is exhausted - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify web search count is captured @@ -1900,9 +1905,9 @@ async def run_test(): response = asyncio.run(run_test()) assert response == mock_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify web search count is captured @@ -1947,9 +1952,9 @@ async def run_test(): asyncio.run(run_test()) # Capture completes before asyncio.run() returns - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify web search count is captured @@ -1963,25 +1968,57 @@ async def run_test(): # ======================= -def test_no_distinct_id_uses_trace_id_and_personless( - mock_client, mock_anthropic_response +@pytest.mark.parametrize( + "distinct_id", [None, "", " "], ids=["missing", "empty", "blank"] +) +@pytest.mark.parametrize("stream", [False, True], ids=["response", "stream"]) +@pytest.mark.parametrize("is_async", [False, True], ids=["sync", "async"]) +async def test_no_distinct_id_uses_trace_id_and_personless( + mock_client, + mock_anthropic_response, + mock_anthropic_stream_with_tools, + is_async, + stream, + distinct_id, ): """When no distinct_id is provided and no outer context, trace_id is used and event is personless.""" - with patch( - "anthropic.resources.Messages.create", return_value=mock_anthropic_response - ): - client = Anthropic(api_key="test-key", posthog_client=mock_client) - client.messages.create( - model="claude-3-opus-20240229", - messages=[{"role": "user", "content": "Hello"}], - posthog_trace_id="trace-123", + request = { + "model": "claude-3-opus-20240229", + "messages": [{"role": "user", "content": "Hello"}], + "posthog_trace_id": "trace-123", + "posthog_properties": {"$process_person_profile": True}, + **({"posthog_distinct_id": distinct_id} if distinct_id is not None else {}), + **({"stream": True} if stream else {}), + } + if is_async: + + async def stream_events(): + for event in mock_anthropic_stream_with_tools: + yield event + + async def create(**kwargs): + return stream_events() if stream else mock_anthropic_response + + with patch("anthropic.resources.AsyncMessages.create", side_effect=create): + client = AsyncAnthropic(api_key="test-key", posthog_client=mock_client) + response = await client.messages.create(**request) + if stream: + [event async for event in response] + else: + provider_response = ( + mock_anthropic_stream_with_tools if stream else mock_anthropic_response ) + with patch( + "anthropic.resources.Messages.create", return_value=provider_response + ): + client = Anthropic(api_key="test-key", posthog_client=mock_client) + response = client.messages.create(**request) + if stream: + list(response) - call_args = mock_client.capture.call_args[1] - props = call_args["properties"] - - assert call_args["distinct_id"] == "trace-123" - assert props["$process_person_profile"] is False + call_args = mock_client.capture_ai.call_args[1] + assert call_args["distinct_id"] == "trace-123" + assert call_args["options"] == {"process_person_profile": False} def test_explicit_distinct_id_creates_person_profile( @@ -1999,14 +2036,12 @@ def test_explicit_distinct_id_creates_person_profile( posthog_trace_id="trace-123", ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "user-123" - assert ( - "$process_person_profile" not in props - or props["$process_person_profile"] is not False - ) + assert "options" not in call_args + assert "$process_person_profile" not in props def test_outer_context_distinct_id_is_used(mock_client, mock_anthropic_response): @@ -2023,14 +2058,12 @@ def test_outer_context_distinct_id_is_used(mock_client, mock_anthropic_response) posthog_trace_id="trace-123", ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "outer-user-456" - assert ( - "$process_person_profile" not in props - or props["$process_person_profile"] is not False - ) + assert "options" not in call_args + assert "$process_person_profile" not in props def test_explicit_distinct_id_overrides_outer_context( @@ -2050,7 +2083,7 @@ def test_explicit_distinct_id_overrides_outer_context( posthog_trace_id="trace-123", ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] assert call_args["distinct_id"] == "explicit-user-789" @@ -2067,7 +2100,7 @@ def test_integration_stop_reason(mock_client): posthog_distinct_id="test-id", ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_stop_reason"] in ("end_turn", "max_tokens") assert props["$ai_provider"] == "anthropic" assert props["$ai_input_tokens"] > 0 @@ -2168,9 +2201,9 @@ async def test_streaming_sync_async_accumulation_parity(mock_client): 0, ) list(sync_response) - sync_properties = mock_client.capture.call_args.kwargs["properties"] + sync_properties = mock_client.capture_ai.call_args.kwargs["properties"] - mock_client.capture.reset_mock() + mock_client.capture_ai.reset_mock() async_client = AsyncAnthropic(api_key="test-key", posthog_client=mock_client) async_response = async_client.messages._track_streaming_response( @@ -2184,7 +2217,7 @@ async def test_streaming_sync_async_accumulation_parity(mock_client): 0, ) [event async for event in async_response] - async_properties = mock_client.capture.call_args.kwargs["properties"] + async_properties = mock_client.capture_ai.call_args.kwargs["properties"] parity_keys = ( "$ai_input", @@ -2224,9 +2257,9 @@ async def test_streaming_sync_async_exceptions_capture_and_close(mock_client): list(stream) assert sync_source.closed is True - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - mock_client.capture.reset_mock() + mock_client.capture_ai.reset_mock() async_source = FailingRecordingAsyncStream([]) async_client = AsyncAnthropic(api_key="test-key", posthog_client=mock_client) @@ -2245,7 +2278,7 @@ async def test_streaming_sync_async_exceptions_capture_and_close(mock_client): [event async for event in stream] assert async_source.closed is True - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 def test_messages_stream_preserves_native_manager_helpers_close_and_tracking( @@ -2269,8 +2302,8 @@ def test_messages_stream_preserves_native_manager_helpers_close_and_tracking( assert text == ["Hi"] assert source.closed is True - assert mock_client.capture.call_count == 1 - assert mock_client.capture.call_args.kwargs["distinct_id"] == "test-user" + assert mock_client.capture_ai.call_count == 1 + assert mock_client.capture_ai.call_args.kwargs["distinct_id"] == "test-user" assert "posthog_distinct_id" not in client.post.call_args.kwargs @@ -2283,15 +2316,19 @@ def test_messages_stream_captures_initial_request_error(mock_client): messages=[{"role": "user", "content": "Foo"}], max_tokens=1, posthog_distinct_id="test-user", + posthog_options={"process_person_profile": False}, ) with pytest.raises(RuntimeError, match="401 unauthorized"): with manager: pass - assert mock_client.capture.call_count == 1 - props = mock_client.capture.call_args.kwargs["properties"] + assert mock_client.capture_ai.call_count == 1 + props = mock_client.capture_ai.call_args.kwargs["properties"] assert props["$ai_is_error"] is True assert props["$ai_error"] == "401 unauthorized" + assert mock_client.capture_ai.call_args.kwargs["options"] == { + "process_person_profile": False + } def test_messages_stream_tolerates_provider_manager_internals_changing(mock_client): @@ -2331,8 +2368,8 @@ async def test_async_messages_stream_preserves_provider_contract_and_manager( assert text == ["Hi"] assert source.closed is True - assert mock_client.capture.call_count == 1 - assert mock_client.capture.call_args.kwargs["distinct_id"] == "test-user" + assert mock_client.capture_ai.call_count == 1 + assert mock_client.capture_ai.call_args.kwargs["distinct_id"] == "test-user" assert "posthog_distinct_id" not in client.post.call_args.kwargs @@ -2346,15 +2383,19 @@ async def test_async_messages_stream_captures_initial_request_error(mock_client) messages=[{"role": "user", "content": "Foo"}], max_tokens=1, posthog_distinct_id="test-user", + posthog_options={"process_person_profile": False}, ) with pytest.raises(RuntimeError, match="401 unauthorized"): async with manager: pass - assert mock_client.capture.call_count == 1 - props = mock_client.capture.call_args.kwargs["properties"] + assert mock_client.capture_ai.call_count == 1 + props = mock_client.capture_ai.call_args.kwargs["properties"] assert props["$ai_is_error"] is True assert props["$ai_error"] == "401 unauthorized" + assert mock_client.capture_ai.call_args.kwargs["options"] == { + "process_person_profile": False + } def test_async_messages_stream_tolerates_provider_manager_internals_changing( @@ -2399,7 +2440,7 @@ async def mock_async_create(**kwargs): events = [event async for event in stream] assert len(events) == 3 - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 def test_messages_streaming_early_exit_closes_provider_stream(mock_client): @@ -2422,7 +2463,7 @@ def test_messages_streaming_early_exit_closes_provider_stream(mock_client): break assert source.closed is True - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 @pytest.mark.asyncio @@ -2451,24 +2492,7 @@ async def mock_async_create(**kwargs): break assert source.closed is True - assert mock_client.capture.call_count == 1 - - -def test_ai_lane_client_routes_through_capture_ai(mock_client, mock_anthropic_response): - mock_client.enable_full_ai_capture = True - with patch( - "anthropic.resources.Messages.create", return_value=mock_anthropic_response - ): - client = Anthropic(api_key="test-key", posthog_client=mock_client) - client.messages.create( - model="claude-3-opus-20240229", - messages=[{"role": "user", "content": "Hello"}], - posthog_distinct_id="test-id", - ) - - mock_client.capture.assert_not_called() assert mock_client.capture_ai.call_count == 1 - assert mock_client.capture_ai.call_args[1]["event"] == "$ai_generation" def test_multimodal_client_skips_media_redaction(mock_client, mock_anthropic_response): @@ -2503,3 +2527,93 @@ def test_multimodal_client_skips_media_redaction(mock_client, mock_anthropic_res assert mock_client.capture_ai.call_count == 1 props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_input"][0]["content"][0]["source"]["data"] == image_data + + +_OPTIONS_CALL_KWARGS = { + "model": "claude-haiku-4-5", + "messages": [{"role": "user", "content": "Foo"}], + "max_tokens": 1, +} + + +async def _call_anthropic_with_options(kind, is_async, mock_client, posthog_kwargs): + """Run one wrapper call and return the arguments the provider received.""" + client_class = AsyncAnthropic if is_async else Anthropic + client = client_class(api_key="test-key", posthog_client=mock_client) + + if kind == "stream_manager": + # messages.stream() builds the request itself, so record the HTTP call. + if is_async: + client.post = AsyncMock( + return_value=RecordingAsyncStream(_anthropic_raw_stream_events()) + ) + manager = client.messages.stream(**_OPTIONS_CALL_KWARGS, **posthog_kwargs) + async with manager as stream: + _ = [chunk async for chunk in stream.text_stream] + else: + client.post = Mock( + return_value=RecordingStream(_anthropic_raw_stream_events()) + ) + with client.messages.stream( + **_OPTIONS_CALL_KWARGS, **posthog_kwargs + ) as stream: + list(stream.text_stream) + return client.post.call_args + + stream = kind == "create_stream" + provider_calls = [] + + def respond(kwargs): + provider_calls.append(kwargs) + if not stream: + return create_mock_response() + events = _anthropic_stream_events() + return RecordingAsyncStream(events) if is_async else RecordingStream(events) + + async def async_create(self, **kwargs): + return respond(kwargs) + + def sync_create(self, **kwargs): + return respond(kwargs) + + target = "AsyncMessages" if is_async else "Messages" + with patch( + f"anthropic.resources.messages.{target}.create", + new=async_create if is_async else sync_create, + ): + call_kwargs = {**_OPTIONS_CALL_KWARGS, "stream": stream, **posthog_kwargs} + result = client.messages.create(**call_kwargs) + if is_async: + result = await result + if stream: + if is_async: + _ = [event async for event in result] + else: + list(result) + assert len(provider_calls) == 1 + return provider_calls[0] + + +@pytest.mark.parametrize( + "case", POSTHOG_OPTIONS_CASES, ids=[case[0] for case in POSTHOG_OPTIONS_CASES] +) +@pytest.mark.parametrize("kind", ["create", "create_stream", "stream_manager"]) +@pytest.mark.parametrize("is_async", [False, True], ids=["sync", "async"]) +async def test_posthog_options_reach_capture_and_not_the_provider( + mock_client, caplog, is_async, kind, case +): + _, distinct_id, posthog_options, expected, warns = case + + with caplog.at_level("WARNING", logger="posthog"): + provider_call = await _call_anthropic_with_options( + kind, + is_async, + mock_client, + posthog_call_kwargs(distinct_id, posthog_options), + ) + + assert "posthog_" not in repr(provider_call) + assert mock_client.capture_ai.call_count == 1 + assert_captured_options( + mock_client.capture_ai.call_args.kwargs, expected, warns, caplog + ) diff --git a/posthog/test/ai/claude_agent_sdk/test_client.py b/posthog/test/ai/claude_agent_sdk/test_client.py index 6ceb3452a..f902313e1 100644 --- a/posthog/test/ai/claude_agent_sdk/test_client.py +++ b/posthog/test/ai/claude_agent_sdk/test_client.py @@ -77,11 +77,15 @@ def analytics(): def events(ph, name): return [ call.kwargs - for call in ph.capture.call_args_list + for call in ph.capture_ai.call_args_list if call.kwargs["event"] == name ] +def event_options(event): + return event.get("options") or {} + + @pytest.mark.asyncio async def test_multiturn_stream_tool_parentage_input_promotion_and_final_trace(sdk): ph = analytics() @@ -196,7 +200,7 @@ async def test_multiturn_stream_tool_parentage_input_promotion_and_final_trace(s assert { event["properties"]["$ai_trace_id"] for event in events(ph, "$ai_generation") } == {"trace"} - for event in ph.capture.call_args_list: + for event in ph.capture_ai.call_args_list: assert event.kwargs["distinct_id"] == "user" assert event.kwargs["groups"] == {"team": "sdk"} assert event.kwargs["properties"]["environment"] == "test" @@ -223,7 +227,7 @@ async def test_result_fallback_and_privacy_without_person_identity(sdk, private) generation = events(ph, "$ai_generation")[0] props = generation["properties"] assert generation["distinct_id"] == "trace" - assert props["$process_person_profile"] is False + assert event_options(generation)["process_person_profile"] is False assert props["$ai_input"] == ( None if private else [{"role": "user", "content": "secret"}] ) @@ -238,7 +242,7 @@ async def test_result_fallback_and_privacy_without_person_identity(sdk, private) assert props["$ai_total_cost_usd"] == 0.01 assert not events(ph, "$ai_trace") await client.disconnect() - assert events(ph, "$ai_trace")[0]["properties"]["$process_person_profile"] is False + assert event_options(events(ph, "$ai_trace")[0])["process_person_profile"] is False @pytest.mark.asyncio @@ -277,7 +281,7 @@ async def test_options_are_copied_and_delegation_preserves_arguments(sdk, partia @pytest.mark.asyncio async def test_instrumentation_failures_never_interrupt_delivery_or_disconnect(sdk): ph = analytics() - ph.capture.side_effect = RuntimeError("capture failure") + ph.capture_ai.side_effect = RuntimeError("capture failure") ph.flush.side_effect = RuntimeError("flush failure") client = PostHogClaudeSDKClient(posthog_client=ph) await client.query("prompt") @@ -317,11 +321,11 @@ async def query(**kwargs): generation = events(ph, "$ai_generation")[0] trace = events(ph, "$ai_trace")[0] assert generation["distinct_id"] == generation["properties"]["$ai_trace_id"] - assert generation["properties"]["$process_person_profile"] is False + assert event_options(generation)["process_person_profile"] is False assert trace["distinct_id"] == ( str(resolved) if resolved else trace["properties"]["$ai_trace_id"] ) - assert ("$process_person_profile" in trace["properties"]) is (not bool(resolved)) + assert ("process_person_profile" in event_options(trace)) is (not bool(resolved)) @pytest.mark.parametrize("resolved", [None, "person", 123, ""]) @@ -369,7 +373,7 @@ async def consume(): with pytest.raises(asyncio.CancelledError): await task assert finalized.is_set() - ph.capture.assert_not_called() + ph.capture_ai.assert_not_called() ph.flush.assert_not_called() diff --git a/posthog/test/ai/claude_agent_sdk/test_processor.py b/posthog/test/ai/claude_agent_sdk/test_processor.py index 548fb8244..6aceb6ce8 100644 --- a/posthog/test/ai/claude_agent_sdk/test_processor.py +++ b/posthog/test/ai/claude_agent_sdk/test_processor.py @@ -8,6 +8,7 @@ import pytest +from posthog.test.ai.utils import POSTHOG_OPTIONS_CASES, assert_captured_options from posthog.version import VERSION try: @@ -173,7 +174,7 @@ def test_initialization(self, mock_client): assert proc._properties == {"env": "test"} def test_initialization_defaults(self): - with patch("posthog.ai.claude_agent_sdk.processor.setup") as mock_setup: + with patch("posthog.ai.utils.setup") as mock_setup: mock_setup.return_value = MagicMock() proc = PostHogClaudeAgentProcessor() assert proc._distinct_id is None @@ -202,7 +203,7 @@ async def test_emits_generation_from_stream_events(self, processor, mock_client) collected.append(msg) # Should have captured $ai_generation + $ai_trace - calls = mock_client.capture.call_args_list + calls = mock_client.capture_ai.call_args_list events = [c.kwargs.get("event") or c[1].get("event") for c in calls] assert "$ai_generation" in events assert "$ai_trace" in events @@ -257,7 +258,7 @@ async def test_message_delta_usage_is_cumulative_with_server_tools( gen_call = next( c - for c in mock_client.capture.call_args_list + for c in mock_client.capture_ai.call_args_list if (c.kwargs.get("event") or c[1].get("event")) == "$ai_generation" ) props = gen_call.kwargs.get("properties") or gen_call[1].get("properties") @@ -288,7 +289,7 @@ async def test_message_delta_without_input_counts_keeps_message_start( gen_call = next( c - for c in mock_client.capture.call_args_list + for c in mock_client.capture_ai.call_args_list if (c.kwargs.get("event") or c[1].get("event")) == "$ai_generation" ) props = gen_call.kwargs.get("properties") or gen_call[1].get("properties") @@ -322,7 +323,7 @@ async def test_emits_cache_creation_ttl_breakdown_from_stream_events( generation_call = next( call - for call in mock_client.capture.call_args_list + for call in mock_client.capture_ai.call_args_list if (call.kwargs.get("event") or call[1].get("event")) == "$ai_generation" ) props = generation_call.kwargs.get("properties") or generation_call[1].get( @@ -361,7 +362,7 @@ async def test_emits_multiple_generations_for_multi_turn( gen_calls = [ c - for c in mock_client.capture.call_args_list + for c in mock_client.capture_ai.call_args_list if (c.kwargs.get("event") or c[1].get("event")) == "$ai_generation" ] assert len(gen_calls) == 2 @@ -393,7 +394,7 @@ async def test_fallback_generation_from_result_when_no_stream_events( gen_calls = [ c - for c in mock_client.capture.call_args_list + for c in mock_client.capture_ai.call_args_list if (c.kwargs.get("event") or c[1].get("event")) == "$ai_generation" ] assert len(gen_calls) == 1 @@ -424,7 +425,7 @@ async def test_fallback_copies_result_usage_before_capture( generation_call = next( call - for call in mock_client.capture.call_args_list + for call in mock_client.capture_ai.call_args_list if (call.kwargs.get("event") or call[1].get("event")) == "$ai_generation" ) props = generation_call.kwargs.get("properties") or generation_call[1].get( @@ -466,7 +467,7 @@ async def test_emits_span_for_tool_use(self, processor, mock_client): span_calls = [ c - for c in mock_client.capture.call_args_list + for c in mock_client.capture_ai.call_args_list if (c.kwargs.get("event") or c[1].get("event")) == "$ai_span" ] assert len(span_calls) == 1 @@ -497,7 +498,7 @@ async def test_emits_trace_on_result(self, processor, mock_client): trace_calls = [ c - for c in mock_client.capture.call_args_list + for c in mock_client.capture_ai.call_args_list if (c.kwargs.get("event") or c[1].get("event")) == "$ai_trace" ] assert len(trace_calls) == 1 @@ -524,7 +525,7 @@ async def test_trace_emits_error_status(self, processor, mock_client): trace_calls = [ c - for c in mock_client.capture.call_args_list + for c in mock_client.capture_ai.call_args_list if (c.kwargs.get("event") or c[1].get("event")) == "$ai_trace" ] assert len(trace_calls) == 1 @@ -548,7 +549,7 @@ async def test_client_privacy_mode_redacts_generation_input(self, mock_client): async for _ in proc.query(prompt="secret", options=ClaudeAgentOptions()): pass - properties = mock_client.capture.call_args.kwargs["properties"] + properties = mock_client.capture_ai.call_args.kwargs["properties"] assert properties["$ai_input"] is None @pytest.mark.asyncio @@ -577,12 +578,12 @@ async def test_per_call_privacy_mode_cannot_disable_processor_mode( ): pass - properties = mock_client.capture.call_args.kwargs["properties"] + properties = mock_client.capture_ai.call_args.kwargs["properties"] assert properties["$ai_input"] is None @pytest.mark.asyncio async def test_client_without_privacy_mode_captures_content(self): - client = SimpleNamespace(capture=MagicMock()) + client = SimpleNamespace(capture_ai=MagicMock()) proc = PostHogClaudeAgentProcessor(client=client, distinct_id="user") messages = [_make_message_start(), _make_message_stop()] @@ -593,7 +594,7 @@ async def test_client_without_privacy_mode_captures_content(self): async for _ in proc.query(prompt="visible", options=ClaudeAgentOptions()): pass - properties = client.capture.call_args.kwargs["properties"] + properties = client.capture_ai.call_args.kwargs["properties"] assert properties["$ai_input"] == [{"role": "user", "content": "visible"}] @pytest.mark.asyncio @@ -634,7 +635,7 @@ async def test_privacy_mode_redacts_tool_input(self, mock_client): span_calls = [ c - for c in mock_client.capture.call_args_list + for c in mock_client.capture_ai.call_args_list if (c.kwargs.get("event") or c[1].get("event")) == "$ai_span" ] assert len(span_calls) == 1 @@ -645,7 +646,7 @@ async def test_privacy_mode_redacts_tool_input(self, mock_client): generation_call = next( call - for call in mock_client.capture.call_args_list + for call in mock_client.capture_ai.call_args_list if (call.kwargs.get("event") or call[1].get("event")) == "$ai_generation" ) generation_props = generation_call.kwargs.get("properties") or generation_call[ @@ -694,7 +695,7 @@ async def test_data_url_prompt_and_tool_use_base64_are_redacted( gen_calls = [ c - for c in mock_client.capture.call_args_list + for c in mock_client.capture_ai.call_args_list if (c.kwargs.get("event") or c[1].get("event")) == "$ai_generation" ] assert len(gen_calls) == 2 @@ -719,7 +720,7 @@ async def test_data_url_prompt_and_tool_use_base64_are_redacted( class TestPersonlessMode: @pytest.mark.asyncio - async def test_no_distinct_id_sets_process_person_profile_false(self, mock_client): + async def test_no_distinct_id_sets_personless_option(self, mock_client): proc = PostHogClaudeAgentProcessor( client=mock_client, distinct_id=None, @@ -742,9 +743,8 @@ async def test_no_distinct_id_sets_process_person_profile_false(self, mock_clien ): pass - for call in mock_client.capture.call_args_list: - props = call.kwargs.get("properties") or call[1].get("properties") - assert props.get("$process_person_profile") is False + for call in mock_client.capture_ai.call_args_list: + assert call.kwargs["options"] == {"process_person_profile": False} assert call.kwargs["distinct_id"] == "trace-fallback" @@ -757,7 +757,7 @@ def test_explicit_groups_override_preserves_empty_groups(self, mock_client): proc._capture_event("$ai_trace", {}, groups={}) - assert mock_client.capture.call_args.kwargs["groups"] == {} + assert mock_client.capture_ai.call_args.kwargs["groups"] == {} def test_default_properties_keep_existing_precedence(self, mock_client): proc = PostHogClaudeAgentProcessor( @@ -770,20 +770,22 @@ def test_default_properties_keep_existing_precedence(self, mock_client): {"environment": "event", "$ai_trace_id": "trace-id"}, ) - assert mock_client.capture.call_args.kwargs["properties"] == { + assert mock_client.capture_ai.call_args.kwargs["properties"] == { "$ai_lib": "posthog-ai", "$ai_lib_version": VERSION, "environment": "processor", "$ai_trace_id": "trace-id", } - def test_client_without_capture_capability_is_ignored(self): - proc = PostHogClaudeAgentProcessor(client=object()) + def test_client_without_capture_ai_disables_capture_at_construction(self, caplog): + with caplog.at_level(logging.ERROR, logger="posthog"): + proc = PostHogClaudeAgentProcessor(client=object()) + assert "capture_ai" in caplog.text proc._capture_event("$ai_trace", {}) def test_capture_errors_are_logged_and_suppressed(self, mock_client, caplog): - mock_client.capture.side_effect = RuntimeError("capture failed") + mock_client.capture_ai.side_effect = RuntimeError("capture failed") proc = PostHogClaudeAgentProcessor(client=mock_client) with caplog.at_level(logging.DEBUG, logger="posthog"): @@ -814,7 +816,7 @@ async def test_instance_properties_merged(self, mock_client): async for _ in proc.query(prompt="Hi", options=ClaudeAgentOptions()): pass - for call in mock_client.capture.call_args_list: + for call in mock_client.capture_ai.call_args_list: props = call.kwargs.get("properties") or call[1].get("properties") assert props.get("app") == "stamphog" assert props.get("version") == "1.0" @@ -839,7 +841,7 @@ async def test_per_call_properties_merged(self, processor, mock_client): ): pass - for call in mock_client.capture.call_args_list: + for call in mock_client.capture_ai.call_args_list: props = call.kwargs.get("properties") or call[1].get("properties") assert props.get("pr_number") == 42 @@ -867,7 +869,7 @@ def resolver(result): trace_calls = [ c - for c in mock_client.capture.call_args_list + for c in mock_client.capture_ai.call_args_list if (c.kwargs.get("event") or c[1].get("event")) == "$ai_trace" ] assert len(trace_calls) == 1 @@ -972,11 +974,146 @@ async def test_non_config_errors_propagate(self): pass -def test_ai_lane_client_routes_through_capture_ai(mock_client): - mock_client.enable_full_ai_capture = True - processor = PostHogClaudeAgentProcessor(client=mock_client, distinct_id="test-user") - processor._capture_event(event="$ai_trace", properties={}, distinct_id="d") +def _streamed_messages(): + return [ + _make_message_start(), + _make_message_stop(), + _make_assistant_message(tool_uses=[{"id": "tu_1", "name": "Read"}]), + _make_result_message(), + ] + + +def _result_only_messages(): + return [_make_result_message()] + + +# id, messages, the events they emit +CLAUDE_MESSAGE_FLOWS = [ + ("streamed", _streamed_messages, ["$ai_generation", "$ai_span", "$ai_trace"]), + ("result_only", _result_only_messages, ["$ai_generation", "$ai_trace"]), +] + + +def _claude_query(entry_point, client, distinct_id, options): + if entry_point == "module_query": + return posthog_query( + prompt="Hi", + options=ClaudeAgentOptions(), + posthog_client=client, + posthog_distinct_id=distinct_id, + posthog_options=options, + ) + if entry_point == "processor_query": + proc = PostHogClaudeAgentProcessor(client=client, distinct_id=distinct_id) + return proc.query( + prompt="Hi", options=ClaudeAgentOptions(), posthog_options=options + ) + proc = instrument(client=client, distinct_id=distinct_id, options=options) + return proc.query(prompt="Hi", options=ClaudeAgentOptions()) + + +class TestPostHogOptions: + @pytest.mark.asyncio + @pytest.mark.parametrize( + "case", + POSTHOG_OPTIONS_CASES, + ids=[case[0] for case in POSTHOG_OPTIONS_CASES], + ) + @pytest.mark.parametrize( + "flow", CLAUDE_MESSAGE_FLOWS, ids=[flow[0] for flow in CLAUDE_MESSAGE_FLOWS] + ) + @pytest.mark.parametrize( + "entry_point", ["module_query", "processor_query", "instrument"] + ) + async def test_options_reach_every_event_and_not_the_sdk( + self, mock_client, caplog, entry_point, flow, case + ): + _, make_messages, expected_events = flow + _, distinct_id, options, expected, warns = case + sdk_calls = [] + + def fake_sdk_query(**kwargs): + sdk_calls.append(kwargs) + return _fake_query(make_messages()) + + with caplog.at_level(logging.WARNING, logger="posthog"): + with patch( + "posthog.ai.claude_agent_sdk.processor.original_query", + side_effect=fake_sdk_query, + ): + async for _ in _claude_query( + entry_point, mock_client, distinct_id, options + ): + pass + + assert [set(call) for call in sdk_calls] == [{"prompt", "options", "transport"}] + calls = mock_client.capture_ai.call_args_list + assert [call.kwargs["event"] for call in calls] == expected_events + for call in calls: + assert_captured_options(call.kwargs, expected, warns, caplog) - mock_client.capture.assert_not_called() - mock_client.capture_ai.assert_called_once() - assert mock_client.capture_ai.call_args[1]["event"] == "$ai_trace" + @pytest.mark.asyncio + async def test_processor_options_win_over_query_options(self, mock_client): + proc = PostHogClaudeAgentProcessor( + client=mock_client, + distinct_id="user", + options={"cookieless_mode": True}, + ) + + with patch( + "posthog.ai.claude_agent_sdk.processor.original_query", + side_effect=lambda **kw: _fake_query(_streamed_messages()), + ): + async for _ in proc.query( + prompt="Hi", + options=ClaudeAgentOptions(), + posthog_options={ + "cookieless_mode": False, + "disable_skew_correction": True, + }, + ): + pass + + # Like properties, the processor's options win key by key. + for call in mock_client.capture_ai.call_args_list: + assert call.kwargs["options"] == { + "cookieless_mode": True, + "disable_skew_correction": True, + } + + @pytest.mark.asyncio + async def test_sdk_client_options_reach_every_event(self, mock_client): + from posthog.ai.claude_agent_sdk import PostHogClaudeSDKClient + + sdk_client = MagicMock() + + async def noop(*args, **kwargs): + return None + + sdk_client.connect = noop + sdk_client.query = noop + sdk_client.disconnect = noop + sdk_client.receive_response = lambda: _fake_query(_streamed_messages()) + + with patch( + "posthog.ai.claude_agent_sdk.client.ClaudeSDKClient", + return_value=sdk_client, + ): + async with PostHogClaudeSDKClient( + ClaudeAgentOptions(), + posthog_client=mock_client, + posthog_distinct_id="user", + posthog_options={"cookieless_mode": True}, + ) as client: + await client.query("Hi") + async for _ in client.receive_response(): + pass + + calls = mock_client.capture_ai.call_args_list + assert [call.kwargs["event"] for call in calls] == [ + "$ai_generation", + "$ai_span", + "$ai_trace", + ] + for call in calls: + assert call.kwargs["options"] == {"cookieless_mode": True} diff --git a/posthog/test/ai/gemini/test_gemini.py b/posthog/test/ai/gemini/test_gemini.py index c5e8409b3..b8aab03ed 100644 --- a/posthog/test/ai/gemini/test_gemini.py +++ b/posthog/test/ai/gemini/test_gemini.py @@ -1,9 +1,17 @@ import json +import logging import os -from unittest.mock import MagicMock, patch +from unittest.mock import AsyncMock, MagicMock, patch import pytest +from posthog.test.ai.utils import ( + POSTHOG_OPTIONS_CASES, + RecordingAsyncStream, + assert_captured_options, + posthog_call_kwargs, +) + try: from google import genai as google_genai @@ -188,9 +196,9 @@ def test_new_client_basic_generation( ) assert response == mock_gemini_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -261,8 +269,8 @@ def mock_streaming_response(): assert chunks[1].text == "world!" # Check that the streaming event was captured - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -343,8 +351,8 @@ def mock_streaming_response(): assert chunks[1].text == "the weather" # Check that the streaming event was captured with tools - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -373,7 +381,7 @@ def test_new_client_groups(mock_client, mock_google_genai_client, mock_gemini_re posthog_groups={"company": "company_123"}, ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] assert call_args["groups"] == {"company": "company_123"} @@ -392,7 +400,7 @@ def test_new_client_privacy_mode_local( posthog_privacy_mode=True, ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] is None assert props["$ai_output_choices"] is None @@ -414,7 +422,7 @@ def test_new_client_privacy_mode_global( posthog_distinct_id="test-id", ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] is None assert props["$ai_output_choices"] is None @@ -432,7 +440,7 @@ def test_new_client_different_input_formats( client.models.generate_content( model="gemini-2.0-flash", contents="Hello", posthog_distinct_id="test-id" ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] == [{"role": "user", "content": "Hello"}] @@ -443,7 +451,7 @@ def test_new_client_different_input_formats( contents=[{"role": "user", "parts": [{"text": "hey"}]}], posthog_distinct_id="test-id", ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] == [ {"role": "user", "content": [{"type": "text", "text": "hey"}]} @@ -456,7 +464,7 @@ def test_new_client_different_input_formats( contents=[{"role": "user", "parts": [{"text": "Hello "}, {"text": "world"}]}], posthog_distinct_id="test-id", ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] == [ { @@ -469,11 +477,11 @@ def test_new_client_different_input_formats( ] # Test list input with string - mock_client.capture.reset_mock() + mock_client.capture_ai.reset_mock() client.models.generate_content( model="gemini-2.0-flash", contents=["List item"], posthog_distinct_id="test-id" ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] == [{"role": "user", "content": "List item"}] @@ -494,7 +502,7 @@ def test_new_client_model_parameters( max_tokens=100, ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_model_parameters"]["temperature"] == 0.7 assert props["$ai_model_parameters"]["max_tokens"] == 100 @@ -518,7 +526,7 @@ def test_new_client_default_settings( # Call without overriding defaults client.models.generate_content(model="gemini-2.0-flash", contents=["Hello"]) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "default_user" @@ -551,7 +559,7 @@ def test_new_client_override_defaults( posthog_groups={"organization": "special_org"}, ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Check overrides @@ -676,9 +684,9 @@ def test_tool_use_response(mock_client, mock_google_genai_client, mock_gemini_re ) assert response == mock_gemini_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -718,9 +726,9 @@ def test_function_calls_in_output_choices( ) assert response == mock_gemini_response_with_function_calls - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -767,9 +775,9 @@ def test_function_calls_only_no_content( ) assert response == mock_gemini_response_function_calls_only - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -856,7 +864,7 @@ def test_function_call_ids_in_output_choices( } if call_id is not None: expected_call["id"] = call_id - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_output_choices"] == [ {"role": "assistant", "content": [expected_call]} ] @@ -901,7 +909,7 @@ def test_function_call_ids_in_input_history( posthog_distinct_id="test-id", ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] call_block, result_block = [ block for message in props["$ai_input"] @@ -948,9 +956,9 @@ def test_cache_and_reasoning_tokens(mock_client, mock_google_genai_client): ) assert response == mock_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Check that all token types are present @@ -1012,9 +1020,9 @@ def test_streaming_cache_and_reasoning_tokens(mock_client, mock_google_genai_cli assert len(result) == 2 # Check PostHog capture was called - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Check that all token types are present (should use final chunk's usage) @@ -1085,9 +1093,9 @@ def test_web_search_grounding(mock_client, mock_google_genai_client): ) assert response == mock_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify web search count is detected (binary for grounding) @@ -1156,9 +1164,9 @@ def mock_streaming_response(): chunks = list(response) assert len(chunks) == 2 - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify web search count is detected (binary for grounding) @@ -1220,9 +1228,9 @@ def test_empty_grounding_metadata_no_web_search(mock_client, mock_google_genai_c ) assert response == mock_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify web search count is 0 (not present in properties when 0) @@ -1283,9 +1291,9 @@ def test_empty_array_grounding_metadata_no_web_search( ) assert response == mock_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify web search count is 0 (not present in properties when 0) @@ -1325,9 +1333,9 @@ def test_falsy_candidates_no_web_search( ) assert response == mock_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Should not crash and web search count should not be present @@ -1379,9 +1387,9 @@ def test_embed_content_basic( ) assert response == mock_embed_content_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -1415,7 +1423,7 @@ def test_embed_content_with_token_counts( posthog_distinct_id="test-id", ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_input_tokens"] == 13 # 5 + 8 @@ -1433,7 +1441,7 @@ def test_embed_content_without_token_counts( posthog_distinct_id="test-id", ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] # No embedding carried a token count, so the property is omitted, not 0. assert "$ai_input_tokens" not in props @@ -1456,7 +1464,7 @@ def test_streaming_without_usage_omits_token_counts( ) list(response) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert "$ai_input_tokens" not in props assert "$ai_output_tokens" not in props @@ -1476,12 +1484,15 @@ def test_embed_content_privacy_mode( posthog_privacy_mode=True, ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_input"] is None +@pytest.mark.parametrize( + "distinct_id", [None, "", " "], ids=["missing", "empty", "blank"] +) def test_embed_content_no_distinct_id( - mock_client, mock_google_genai_client, mock_embed_content_response + mock_client, mock_google_genai_client, mock_embed_content_response, distinct_id ): mock_google_genai_client.models.embed_content.return_value = ( mock_embed_content_response @@ -1491,14 +1502,16 @@ def test_embed_content_no_distinct_id( client.models.embed_content( model="gemini-embedding-001", contents="Hello", + **({"posthog_distinct_id": distinct_id} if distinct_id is not None else {}), ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Should fall back to trace_id as distinct_id assert call_args["distinct_id"] == props["$ai_trace_id"] - assert props["$process_person_profile"] is False + assert call_args["options"] == {"process_person_profile": False} + assert "$process_person_profile" not in props def test_embed_content_default_params( @@ -1521,7 +1534,7 @@ def test_embed_content_default_params( posthog_properties={"extra": "prop"}, ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "default-id" @@ -1543,8 +1556,8 @@ def test_embed_content_error_handling(mock_client, mock_google_genai_client): ) # Event should still be captured - assert mock_client.capture.call_count == 1 - props = mock_client.capture.call_args[1]["properties"] + assert mock_client.capture_ai.call_count == 1 + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_is_error"] is True assert props["$ai_error"] == "API error" assert props["$ai_http_status"] == 0 @@ -1588,8 +1601,8 @@ def test_embed_content_integration(mock_client): assert all(isinstance(v, float) for v in response.embeddings[0].values) # Verify event captured - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["event"] == "$ai_embedding" assert props["$ai_provider"] == "gemini" @@ -1652,7 +1665,7 @@ def test_stop_reason_captured( posthog_distinct_id="test-id", ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_stop_reason"] == finish_reason_name @@ -1701,8 +1714,8 @@ def mock_streaming_response(): list(response) - assert mock_client.capture.call_count == 1 - props = mock_client.capture.call_args[1]["properties"] + assert mock_client.capture_ai.call_count == 1 + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_stop_reason"] == "STOP" @@ -1718,31 +1731,13 @@ def test_integration_stop_reason(mock_client): posthog_distinct_id="test-id", ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_stop_reason"] is not None assert isinstance(props["$ai_stop_reason"], str) assert props["$ai_provider"] == "gemini" assert props["$ai_input_tokens"] > 0 -def test_ai_lane_client_routes_through_capture_ai( - mock_client, mock_google_genai_client, mock_gemini_response -): - mock_google_genai_client.models.generate_content.return_value = mock_gemini_response - - mock_client.enable_full_ai_capture = True - client = Client(api_key="test-key", posthog_client=mock_client) - client.models.generate_content( - model="gemini-2.0-flash", - contents=["Tell me a fun fact about hedgehogs"], - posthog_distinct_id="test-id", - ) - - mock_client.capture.assert_not_called() - assert mock_client.capture_ai.call_count == 1 - assert mock_client.capture_ai.call_args[1]["event"] == "$ai_generation" - - def _url_context_stream_chunks(): from google.genai import types @@ -1775,6 +1770,151 @@ def test_streaming_url_context_on_earlier_chunk_bills_tool_use_tokens( ) list(response) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_input_tokens"] == 320 assert props["$ai_output_tokens"] == 10 + + +def _gemini_stream_chunk(): + chunk = MagicMock() + chunk.text = "Hi" + usage = MagicMock() + usage.prompt_token_count = 2 + usage.candidates_token_count = 1 + usage.cached_content_token_count = 0 + usage.thoughts_token_count = 0 + chunk.usage_metadata = usage + return chunk + + +@pytest.fixture +def gemini_provider(mock_gemini_response, mock_embed_content_response): + """A genai.Client mock with sync ``models`` and async ``aio.models``.""" + with patch.object(google_genai, "Client") as client_class: + provider = MagicMock() + provider.models.generate_content.return_value = mock_gemini_response + provider.models.generate_content_stream.side_effect = lambda **kwargs: iter( + [_gemini_stream_chunk()] + ) + provider.models.embed_content.return_value = mock_embed_content_response + provider.aio.models.generate_content = AsyncMock( + return_value=mock_gemini_response + ) + provider.aio.models.generate_content_stream = AsyncMock( + side_effect=lambda **kwargs: RecordingAsyncStream([_gemini_stream_chunk()]) + ) + provider.aio.models.embed_content = AsyncMock( + return_value=mock_embed_content_response + ) + client_class.return_value = provider + yield provider + + +# id, client class, models accessor, whether the surface is async +GEMINI_SURFACES = [ + ("client_models", "Client", lambda client: client.models, False), + ("client_aio_models", "Client", lambda client: client.aio.models, True), + ("async_client_models", "AsyncClient", lambda client: client.models, True), +] + + +def _gemini_client(class_name, **kwargs): + from posthog.ai.gemini import AsyncClient + + client_class = AsyncClient if class_name == "AsyncClient" else Client + return client_class(api_key="test-key", **kwargs) + + +async def _call_gemini(models, method, is_async, **kwargs): + result = getattr(models, method)(model="gemini-2.5-flash", contents="Hi", **kwargs) + if is_async: + result = await result + if method == "generate_content_stream": + if is_async: + _ = [chunk async for chunk in result] + else: + list(result) + + +@pytest.mark.parametrize( + "case", POSTHOG_OPTIONS_CASES, ids=[case[0] for case in POSTHOG_OPTIONS_CASES] +) +@pytest.mark.parametrize( + "method", ["generate_content", "generate_content_stream", "embed_content"] +) +@pytest.mark.parametrize( + "surface", GEMINI_SURFACES, ids=[surface[0] for surface in GEMINI_SURFACES] +) +async def test_posthog_options_reach_capture_and_not_the_provider( + mock_client, gemini_provider, caplog, surface, method, case +): + _, class_name, accessor, is_async = surface + _, distinct_id, posthog_options, expected, warns = case + client = _gemini_client(class_name, posthog_client=mock_client) + + with caplog.at_level(logging.WARNING, logger="posthog"): + await _call_gemini( + accessor(client), + method, + is_async, + **posthog_call_kwargs(distinct_id, posthog_options), + ) + + models = gemini_provider.aio.models if is_async else gemini_provider.models + provider_method = getattr(models, method) + assert provider_method.call_count == 1 + assert not any( + key.startswith("posthog_") for key in provider_method.call_args.kwargs + ) + assert mock_client.capture_ai.call_count == 1 + assert_captured_options( + mock_client.capture_ai.call_args.kwargs, expected, warns, caplog + ) + + +@pytest.mark.parametrize( + "method", ["generate_content", "generate_content_stream", "embed_content"] +) +@pytest.mark.parametrize( + "surface", GEMINI_SURFACES, ids=[surface[0] for surface in GEMINI_SURFACES] +) +async def test_posthog_options_merge_over_client_defaults( + mock_client, gemini_provider, surface, method +): + _, class_name, accessor, is_async = surface + client = _gemini_client( + class_name, + posthog_client=mock_client, + posthog_options={"cookieless_mode": True, "disable_skew_correction": True}, + ) + + await _call_gemini(accessor(client), method, is_async, posthog_distinct_id="u") + await _call_gemini( + accessor(client), + method, + is_async, + posthog_distinct_id="u", + posthog_options={"cookieless_mode": False}, + ) + + assert [ + call.kwargs["options"] for call in mock_client.capture_ai.call_args_list + ] == [ + {"cookieless_mode": True, "disable_skew_correction": True}, + {"cookieless_mode": False, "disable_skew_correction": True}, + ] + + +def test_non_dict_client_default_posthog_options_are_ignored( + mock_client, gemini_provider, caplog +): + with caplog.at_level(logging.WARNING, logger="posthog"): + client = Client( + api_key="test-key", posthog_client=mock_client, posthog_options="bad" + ) + client.models.generate_content( + model="gemini-2.5-flash", contents="Hi", posthog_distinct_id="user-1" + ) + + assert "posthog_options must be a dict" in caplog.text + assert "options" not in mock_client.capture_ai.call_args.kwargs diff --git a/posthog/test/ai/gemini/test_gemini_async.py b/posthog/test/ai/gemini/test_gemini_async.py index 9cdc0fdbb..dd9e8f79f 100644 --- a/posthog/test/ai/gemini/test_gemini_async.py +++ b/posthog/test/ai/gemini/test_gemini_async.py @@ -135,9 +135,9 @@ async def test_async_client_basic_generation( ) assert response == mock_gemini_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -168,8 +168,8 @@ async def slow_call(**kwargs): timeout=0.01, ) - assert mock_client.capture.call_count == 1 - event = mock_client.capture.call_args.kwargs + assert mock_client.capture_ai.call_count == 1 + event = mock_client.capture_ai.call_args.kwargs assert event["event"] == "$ai_generation" props = event["properties"] assert props["$ai_http_status"] == 0 @@ -226,8 +226,8 @@ async def mock_streaming_response(): assert chunks[1].text == "world!" # Check that the streaming event was captured - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -310,8 +310,8 @@ async def mock_streaming_response(): assert chunks[1].text == "the weather" # Check that the streaming event was captured with tools - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -344,7 +344,7 @@ async def test_async_client_groups( posthog_groups={"company": "company_123"}, ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] assert call_args["groups"] == {"company": "company_123"} @@ -365,7 +365,7 @@ async def test_async_client_privacy_mode_local( posthog_privacy_mode=True, ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] is None assert props["$ai_output_choices"] is None @@ -389,7 +389,7 @@ async def test_async_client_privacy_mode_global( posthog_distinct_id="test-id", ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] is None assert props["$ai_output_choices"] is None @@ -409,7 +409,7 @@ async def test_async_client_different_input_formats( await client.models.generate_content( model="gemini-2.0-flash", contents="Hello", posthog_distinct_id="test-id" ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] == [{"role": "user", "content": "Hello"}] @@ -420,7 +420,7 @@ async def test_async_client_different_input_formats( contents=[{"role": "user", "parts": [{"text": "hey"}]}], posthog_distinct_id="test-id", ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] == [ {"role": "user", "content": [{"type": "text", "text": "hey"}]} @@ -433,7 +433,7 @@ async def test_async_client_different_input_formats( contents=[{"role": "user", "parts": [{"text": "Hello "}, {"text": "world"}]}], posthog_distinct_id="test-id", ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] == [ { @@ -446,11 +446,11 @@ async def test_async_client_different_input_formats( ] # Test list input with string - mock_client.capture.reset_mock() + mock_client.capture_ai.reset_mock() await client.models.generate_content( model="gemini-2.0-flash", contents=["List item"], posthog_distinct_id="test-id" ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] == [{"role": "user", "content": "List item"}] @@ -473,7 +473,7 @@ async def test_async_client_model_parameters( max_tokens=100, ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_model_parameters"]["temperature"] == 0.7 assert props["$ai_model_parameters"]["max_tokens"] == 100 @@ -499,7 +499,7 @@ async def test_async_client_default_settings( # Call without overriding defaults await client.models.generate_content(model="gemini-2.0-flash", contents=["Hello"]) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "default_user" @@ -534,7 +534,7 @@ async def test_async_client_override_defaults( posthog_groups={"organization": "special_org"}, ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Check overrides @@ -613,9 +613,9 @@ async def test_async_function_calls_in_output_choices( ) assert response == mock_gemini_response_with_function_calls - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -676,9 +676,9 @@ async def test_async_cache_and_reasoning_tokens(mock_client, mock_google_genai_c ) assert response == mock_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Check that all token types are present @@ -735,9 +735,9 @@ async def mock_streaming_response(): assert len(result) == 2 # Check PostHog capture was called - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Check that all token types are present (should use final chunk's usage) @@ -799,9 +799,9 @@ async def test_async_web_search_grounding(mock_client, mock_google_genai_client) ) assert response == mock_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify web search count is detected (binary for grounding) @@ -872,9 +872,9 @@ async def mock_streaming_response(): chunks.append(chunk) assert len(chunks) == 2 - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify web search count is detected (binary for grounding) @@ -926,9 +926,9 @@ async def test_async_embed_content_basic( ) assert response == mock_embed_content_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -962,7 +962,7 @@ async def test_async_embed_content_with_token_counts( posthog_distinct_id="test-id", ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_input_tokens"] == 13 # 5 + 8 @@ -980,7 +980,7 @@ async def test_async_embed_content_without_token_counts( posthog_distinct_id="test-id", ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] # No embedding carried a token count, so the property is omitted, not 0. assert "$ai_input_tokens" not in props @@ -1000,7 +1000,7 @@ async def test_async_embed_content_privacy_mode( posthog_privacy_mode=True, ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_input"] is None @@ -1017,12 +1017,13 @@ async def test_async_embed_content_no_distinct_id( contents="Hello", ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Should fall back to trace_id as distinct_id assert call_args["distinct_id"] == props["$ai_trace_id"] - assert props["$process_person_profile"] is False + assert call_args["options"] == {"process_person_profile": False} + assert "$process_person_profile" not in props async def test_async_embed_content_default_params( @@ -1045,7 +1046,7 @@ async def test_async_embed_content_default_params( posthog_properties={"extra": "prop"}, ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "default-id" @@ -1071,8 +1072,8 @@ async def test_async_embed_content_error_handling( ) # Event should still be captured - assert mock_client.capture.call_count == 1 - props = mock_client.capture.call_args[1]["properties"] + assert mock_client.capture_ai.call_count == 1 + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_is_error"] is True assert props["$ai_error"] == "API error" assert props["$ai_http_status"] == 0 @@ -1116,8 +1117,8 @@ async def test_async_embed_content_integration(mock_client): assert all(isinstance(v, float) for v in response.embeddings[0].values) # Verify event captured - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["event"] == "$ai_embedding" assert props["$ai_provider"] == "gemini" @@ -1174,8 +1175,8 @@ async def mock_streaming_response(): chunks.append(chunk) assert len(chunks) == 1 - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] assert call_args["event"] == "$ai_generation" assert call_args["properties"]["$ai_provider"] == "gemini" @@ -1212,6 +1213,6 @@ async def stream(): async for _ in response: pass - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_input_tokens"] == 320 assert props["$ai_output_tokens"] == 10 diff --git a/posthog/test/ai/gemini/test_gemini_parity.py b/posthog/test/ai/gemini/test_gemini_parity.py index 9f7166f7e..b5d893e25 100644 --- a/posthog/test/ai/gemini/test_gemini_parity.py +++ b/posthog/test/ai/gemini/test_gemini_parity.py @@ -230,8 +230,8 @@ async def test_sync_client_aio_models_tracks_generations( assert response is gemini_response provider_client.aio.models.generate_content.assert_awaited_once() - assert posthog_client.capture.call_count == 1 - call_args = posthog_client.capture.call_args[1] + assert posthog_client.capture_ai.call_count == 1 + call_args = posthog_client.capture_ai.call_args[1] assert call_args["distinct_id"] == "test-id" assert call_args["event"] == "$ai_generation" assert call_args["properties"]["$ai_model"] == "gemini-2.0-flash" diff --git a/posthog/test/ai/langchain/test_callbacks.py b/posthog/test/ai/langchain/test_callbacks.py index 68103a5a0..10df3378a 100644 --- a/posthog/test/ai/langchain/test_callbacks.py +++ b/posthog/test/ai/langchain/test_callbacks.py @@ -9,6 +9,8 @@ import pytest +from posthog.test.ai.utils import POSTHOG_OPTIONS_CASES, assert_captured_options + try: from langchain_anthropic.chat_models import ChatAnthropic from langchain_community.chat_models.fake import FakeMessagesListChatModel @@ -185,15 +187,15 @@ def test_basic_chat_chain(mock_client, stream): result = chain.invoke({}, config={"callbacks": callbacks}) assert result.content == "The Los Angeles Dodgers won the World Series in 2020." - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - span_args = mock_client.capture.call_args_list[0][1] + span_args = mock_client.capture_ai.call_args_list[0][1] span_props = span_args["properties"] - generation_args = mock_client.capture.call_args_list[1][1] + generation_args = mock_client.capture_ai.call_args_list[1][1] generation_props = generation_args["properties"] - trace_args = mock_client.capture.call_args_list[2][1] + trace_args = mock_client.capture_ai.call_args_list[2][1] trace_props = trace_args["properties"] # Span is first @@ -262,13 +264,13 @@ async def test_async_basic_chat_chain(mock_client, stream): else: result = await chain.ainvoke({}, config={"callbacks": callbacks}) assert result.content == "The Los Angeles Dodgers won the World Series in 2020." - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - span_args = mock_client.capture.call_args_list[0][1] + span_args = mock_client.capture_ai.call_args_list[0][1] span_props = span_args["properties"] - generation_args = mock_client.capture.call_args_list[1][1] + generation_args = mock_client.capture_ai.call_args_list[1][1] generation_props = generation_args["properties"] - trace_args = mock_client.capture.call_args_list[2][1] + trace_args = mock_client.capture_ai.call_args_list[2][1] trace_props = trace_args["properties"] # Span is first @@ -349,7 +351,7 @@ def _capture_anthropic_usage( ) cb._pop_run_and_capture_generation(run_id, None, response) - return mock_client.capture.call_args.kwargs["properties"] + return mock_client.capture_ai.call_args.kwargs["properties"] @pytest.mark.parametrize( @@ -380,8 +382,8 @@ def test_basic_llm_chain(mock_client, Model, stream): ) assert result == "The Los Angeles Dodgers won the World Series in 2020." - assert mock_client.capture.call_count == 1 - args = mock_client.capture.call_args_list[0][1] + assert mock_client.capture_ai.call_count == 1 + args = mock_client.capture_ai.call_args_list[0][1] props = args["properties"] assert args["event"] == "$ai_generation" @@ -425,8 +427,8 @@ async def test_async_basic_llm_chain(mock_client, Model, stream): ) assert result == "The Los Angeles Dodgers won the World Series in 2020." - assert mock_client.capture.call_count == 1 - args = mock_client.capture.call_args_list[0][1] + assert mock_client.capture_ai.call_count == 1 + args = mock_client.capture_ai.call_args_list[0][1] props = args["properties"] assert args["event"] == "$ai_generation" @@ -455,21 +457,21 @@ def test_trace_id_and_inputs_for_multiple_chains(mock_client): assert result.content == "Bar" # span, generation, span, generation, trace - assert mock_client.capture.call_count == 5 + assert mock_client.capture_ai.call_count == 5 - first_span_args = mock_client.capture.call_args_list[0][1] + first_span_args = mock_client.capture_ai.call_args_list[0][1] first_span_props = first_span_args["properties"] - first_generation_args = mock_client.capture.call_args_list[1][1] + first_generation_args = mock_client.capture_ai.call_args_list[1][1] first_generation_props = first_generation_args["properties"] - second_span_args = mock_client.capture.call_args_list[2][1] + second_span_args = mock_client.capture_ai.call_args_list[2][1] second_span_props = second_span_args["properties"] - second_generation_args = mock_client.capture.call_args_list[3][1] + second_generation_args = mock_client.capture_ai.call_args_list[3][1] second_generation_props = second_generation_args["properties"] - trace_args = mock_client.capture.call_args_list[4][1] + trace_args = mock_client.capture_ai.call_args_list[4][1] trace_props = trace_args["properties"] # Prompt span @@ -536,40 +538,50 @@ def test_personless_mode(mock_client): prompt = ChatPromptTemplate.from_messages([("user", "Foo")]) chain = prompt | FakeMessagesListChatModel(responses=[AIMessage(content="Bar")]) chain.invoke({}, config={"callbacks": [CallbackHandler(mock_client)]}) - assert mock_client.capture.call_count == 3 - span_args = mock_client.capture.call_args_list[0][1] - generation_args = mock_client.capture.call_args_list[1][1] - trace_args = mock_client.capture.call_args_list[2][1] + assert mock_client.capture_ai.call_count == 3 + span_args = mock_client.capture_ai.call_args_list[0][1] + generation_args = mock_client.capture_ai.call_args_list[1][1] + trace_args = mock_client.capture_ai.call_args_list[2][1] # span assert span_args["event"] == "$ai_span" - assert span_args["properties"]["$process_person_profile"] is False + assert span_args["options"] == {"process_person_profile": False} # generation assert generation_args["event"] == "$ai_generation" - assert generation_args["properties"]["$process_person_profile"] is False + assert generation_args["options"] == {"process_person_profile": False} # trace assert trace_args["event"] == "$ai_trace" - assert trace_args["properties"]["$process_person_profile"] is False + assert trace_args["options"] == {"process_person_profile": False} id = uuid.uuid4() chain.invoke( {}, config={"callbacks": [CallbackHandler(mock_client, distinct_id=id)]} ) - assert mock_client.capture.call_count == 6 - span_args = mock_client.capture.call_args_list[3][1] - generation_args = mock_client.capture.call_args_list[4][1] - trace_args = mock_client.capture.call_args_list[5][1] + assert mock_client.capture_ai.call_count == 6 + span_args = mock_client.capture_ai.call_args_list[3][1] + generation_args = mock_client.capture_ai.call_args_list[4][1] + trace_args = mock_client.capture_ai.call_args_list[5][1] # span - assert "$process_person_profile" not in span_args["properties"] + assert "options" not in span_args assert span_args["distinct_id"] == id # generation - assert "$process_person_profile" not in generation_args["properties"] + assert "options" not in generation_args assert generation_args["distinct_id"] == id # trace - assert "$process_person_profile" not in trace_args["properties"] + assert "options" not in trace_args assert trace_args["distinct_id"] == id + # An empty or whitespace distinct id counts as missing. + for blank in ("", " "): + mock_client.capture_ai.reset_mock() + chain.invoke( + {}, config={"callbacks": [CallbackHandler(mock_client, distinct_id=blank)]} + ) + for call in mock_client.capture_ai.call_args_list: + assert call[1]["options"] == {"process_person_profile": False} + assert call[1]["distinct_id"] not in ("", " ") + @pytest.fixture def unauthorized_http_client(): @@ -595,44 +607,44 @@ def test_personless_mode_exception(mock_client, unauthorized_http_client): callbacks = CallbackHandler(mock_client) with pytest.raises(AuthenticationError): chain.invoke({}, config={"callbacks": [callbacks]}) - assert mock_client.capture.call_count == 3 - span_args = mock_client.capture.call_args_list[0][1] - generation_args = mock_client.capture.call_args_list[1][1] - trace_args = mock_client.capture.call_args_list[2][1] + assert mock_client.capture_ai.call_count == 3 + span_args = mock_client.capture_ai.call_args_list[0][1] + generation_args = mock_client.capture_ai.call_args_list[1][1] + trace_args = mock_client.capture_ai.call_args_list[2][1] # span assert span_args["event"] == "$ai_span" - assert span_args["properties"]["$process_person_profile"] is False + assert span_args["options"] == {"process_person_profile": False} # generation assert generation_args["event"] == "$ai_generation" - assert generation_args["properties"]["$process_person_profile"] is False + assert generation_args["options"] == {"process_person_profile": False} # trace assert trace_args["event"] == "$ai_trace" - assert trace_args["properties"]["$process_person_profile"] is False + assert trace_args["options"] == {"process_person_profile": False} id = uuid.uuid4() with pytest.raises(AuthenticationError): chain.invoke( {}, config={"callbacks": [CallbackHandler(mock_client, distinct_id=id)]} ) - assert mock_client.capture.call_count == 6 - span_args = mock_client.capture.call_args_list[3][1] - generation_args = mock_client.capture.call_args_list[4][1] - trace_args = mock_client.capture.call_args_list[5][1] + assert mock_client.capture_ai.call_count == 6 + span_args = mock_client.capture_ai.call_args_list[3][1] + generation_args = mock_client.capture_ai.call_args_list[4][1] + trace_args = mock_client.capture_ai.call_args_list[5][1] # span assert span_args["event"] == "$ai_span" - assert "$process_person_profile" not in span_args["properties"] + assert "options" not in span_args assert span_args["distinct_id"] == id # generation assert generation_args["event"] == "$ai_generation" - assert "$process_person_profile" not in generation_args["properties"] + assert "options" not in generation_args assert generation_args["distinct_id"] == id # trace assert trace_args["event"] == "$ai_trace" - assert "$process_person_profile" not in trace_args["properties"] + assert "options" not in trace_args assert trace_args["distinct_id"] == id @@ -655,9 +667,9 @@ def test_metadata(mock_client): result = chain.invoke({"plan": None}, config={"callbacks": callbacks}) assert result.content == "Bar" - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - span_call_args = mock_client.capture.call_args_list[0][1] + span_call_args = mock_client.capture_ai.call_args_list[0][1] span_call_props = span_call_args["properties"] assert span_call_args["distinct_id"] == "test_id" assert span_call_args["event"] == "$ai_span" @@ -666,7 +678,7 @@ def test_metadata(mock_client): assert "$ai_parent_id" in span_call_props assert "$ai_span_id" in span_call_props - generation_call_args = mock_client.capture.call_args_list[1][1] + generation_call_args = mock_client.capture_ai.call_args_list[1][1] generation_call_props = generation_call_args["properties"] assert generation_call_args["distinct_id"] == "test_id" assert generation_call_args["event"] == "$ai_generation" @@ -679,7 +691,7 @@ def test_metadata(mock_client): assert generation_call_props["$ai_http_status"] == 200 assert isinstance(generation_call_props["$ai_latency"], float) - trace_call_args = mock_client.capture.call_args_list[2][1] + trace_call_args = mock_client.capture_ai.call_args_list[2][1] trace_call_props = trace_call_args["properties"] assert trace_call_args["distinct_id"] == "test_id" assert trace_call_args["event"] == "$ai_trace" @@ -742,8 +754,8 @@ def test_graph_state(mock_client): assert isinstance(result["messages"][2], AIMessage) assert result["messages"][2].content == "It's a type of greeble." - assert mock_client.capture.call_count == 6 - calls = [call[1] for call in mock_client.capture.call_args_list] + assert mock_client.capture_ai.call_count == 6 + calls = [call[1] for call in mock_client.capture_ai.call_args_list] # The trace event is captured at the end trace_args = calls[-1] @@ -867,8 +879,8 @@ def runnable(_): assert callbacks._runs == {} assert callbacks._parent_tree == {} - assert mock_client.capture.call_count == 1 - trace_call_args = mock_client.capture.call_args_list[0][1] + assert mock_client.capture_ai.call_count == 1 + trace_call_args = mock_client.capture_ai.call_args_list[0][1] assert trace_call_args["event"] == "$ai_trace" assert trace_call_args["properties"]["$ai_span_name"] == "runnable" @@ -895,8 +907,8 @@ def unauthorized(request): assert callbacks._runs == {} assert callbacks._parent_tree == {} - assert mock_client.capture.call_count == 3 - generation_args = mock_client.capture.call_args_list[1][1] + assert mock_client.capture_ai.call_count == 3 + generation_args = mock_client.capture_ai.call_args_list[1][1] props = generation_args["properties"] assert props["$ai_http_status"] == 401 assert props["$ai_input"] == [{"role": "user", "content": "Foo"}] @@ -928,9 +940,9 @@ def test_openai_chain(mock_client): approximate_latency = math.floor(time.time() - start_time) assert result.content == "Bar" - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - gen_args = mock_client.capture.call_args_list[1][1] + gen_args = mock_client.capture_ai.call_args_list[1][1] gen_props = gen_args["properties"] assert gen_args["event"] == "$ai_generation" assert gen_props["$ai_trace_id"] == "test-trace-id" @@ -990,11 +1002,11 @@ def test_openai_captures_multiple_generations(mock_client): result = chain.invoke({}, config={"callbacks": [callbacks]}) assert result.content == "Bar" - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - gen_args = mock_client.capture.call_args_list[1][1] + gen_args = mock_client.capture_ai.call_args_list[1][1] gen_props = gen_args["properties"] - trace_args = mock_client.capture.call_args_list[2][1] + trace_args = mock_client.capture_ai.call_args_list[2][1] trace_props = trace_args["properties"] assert gen_args["event"] == "$ai_generation" @@ -1053,11 +1065,11 @@ def test_openai_streaming(mock_client): result = sum(result[1:], result[0]) assert result.content == "Bar" - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - gen_args = mock_client.capture.call_args_list[1][1] + gen_args = mock_client.capture_ai.call_args_list[1][1] gen_props = gen_args["properties"] - trace_args = mock_client.capture.call_args_list[2][1] + trace_args = mock_client.capture_ai.call_args_list[2][1] trace_props = trace_args["properties"] assert gen_args["event"] == "$ai_generation" @@ -1097,11 +1109,11 @@ async def test_async_openai_streaming(mock_client): result = sum(result[1:], result[0]) assert result.content == "Bar" - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - gen_args = mock_client.capture.call_args_list[1][1] + gen_args = mock_client.capture_ai.call_args_list[1][1] gen_props = gen_args["properties"] - trace_args = mock_client.capture.call_args_list[2][1] + trace_args = mock_client.capture_ai.call_args_list[2][1] trace_props = trace_args["properties"] assert gen_args["event"] == "$ai_generation" @@ -1135,8 +1147,8 @@ def test_base_url_retrieval(mock_client, unauthorized_http_client): with pytest.raises(AuthenticationError): chain.invoke({}, config={"callbacks": [callbacks]}) - assert mock_client.capture.call_count == 3 - generation_call = mock_client.capture.call_args_list[1][1] + assert mock_client.capture_ai.call_count == 3 + generation_call = mock_client.capture_ai.call_args_list[1][1] assert generation_call["properties"]["$ai_base_url"] == "https://test.posthog.com" @@ -1152,8 +1164,8 @@ def test_groups(mock_client): callbacks = CallbackHandler(mock_client, groups={"company": "test_company"}) chain.invoke({}, config={"callbacks": [callbacks]}) - assert mock_client.capture.call_count == 3 - generation_call = mock_client.capture.call_args_list[1][1] + assert mock_client.capture_ai.call_count == 3 + generation_call = mock_client.capture_ai.call_args_list[1][1] assert generation_call["groups"] == {"company": "test_company"} @@ -1169,8 +1181,8 @@ def test_privacy_mode_local(mock_client): callbacks = CallbackHandler(mock_client, privacy_mode=True) chain.invoke({}, config={"callbacks": [callbacks]}) - assert mock_client.capture.call_count == 3 - generation_call = mock_client.capture.call_args_list[1][1] + assert mock_client.capture_ai.call_count == 3 + generation_call = mock_client.capture_ai.call_args_list[1][1] assert generation_call["properties"]["$ai_input"] is None assert generation_call["properties"]["$ai_output_choices"] is None @@ -1188,8 +1200,8 @@ def test_privacy_mode_global(mock_client): callbacks = CallbackHandler(mock_client) chain.invoke({}, config={"callbacks": [callbacks]}) - assert mock_client.capture.call_count == 3 - generation_call = mock_client.capture.call_args_list[1][1] + assert mock_client.capture_ai.call_count == 3 + generation_call = mock_client.capture_ai.call_args_list[1][1] assert generation_call["properties"]["$ai_input"] is None assert generation_call["properties"]["$ai_output_choices"] is None @@ -1219,11 +1231,11 @@ def test_anthropic_chain(mock_client): approximate_latency = math.floor(time.time() - start_time) assert result.content == "Bar" - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - gen_args = mock_client.capture.call_args_list[1][1] + gen_args = mock_client.capture_ai.call_args_list[1][1] gen_props = gen_args["properties"] - trace_args = mock_client.capture.call_args_list[2][1] + trace_args = mock_client.capture_ai.call_args_list[2][1] trace_props = trace_args["properties"] assert gen_args["event"] == "$ai_generation" @@ -1279,11 +1291,11 @@ async def test_async_anthropic_streaming(mock_client): result = sum(result[1:], result[0]) assert result.content == "Bar" - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - gen_args = mock_client.capture.call_args_list[1][1] + gen_args = mock_client.capture_ai.call_args_list[1][1] gen_props = gen_args["properties"] - trace_args = mock_client.capture.call_args_list[2][1] + trace_args = mock_client.capture_ai.call_args_list[2][1] trace_props = trace_args["properties"] assert gen_args["event"] == "$ai_generation" @@ -1385,8 +1397,8 @@ def test_tool_calls(mock_client): callbacks = CallbackHandler(mock_client) chain.invoke({}, config={"callbacks": [callbacks]}) - assert mock_client.capture.call_count == 3 - generation_call = mock_client.capture.call_args_list[1][1] + assert mock_client.capture_ai.call_count == 3 + generation_call = mock_client.capture_ai.call_args_list[1][1] assert generation_call["properties"]["$ai_output_choices"][0]["tool_calls"] == [ { "type": "function", @@ -1421,9 +1433,9 @@ async def sleep(x): # -> Any: chain2.ainvoke({}, config={"callbacks": [cb]}), ) approximate_latency = math.floor(time.time() - start_time) - assert mock_client.capture.call_count == 4 + assert mock_client.capture_ai.call_count == 4 - calls = [call.kwargs for call in mock_client.capture.call_args_list] + calls = [call.kwargs for call in mock_client.capture_ai.call_args_list] assert sorted(call["event"] for call in calls) == [ "$ai_generation", "$ai_span", @@ -1465,7 +1477,7 @@ def get_weather(city: Literal["nyc", "sf"]): mock_client, trace_id="test-trace-id", distinct_id="test-distinct-id" ) graph.invoke(inputs, config={"callbacks": [cb]}) - calls = [call[1] for call in mock_client.capture.call_args_list] + calls = [call[1] for call in mock_client.capture_ai.call_args_list] assert len(calls) == 15 for call in calls: assert call["properties"]["$ai_trace_id"] == "test-trace-id" @@ -1491,15 +1503,15 @@ def test_span_set_parent_ids(mock_client, trace_id): chain = prompt | model chain.invoke({}, config={"callbacks": callbacks}) - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - span_props = mock_client.capture.call_args_list[0][1] + span_props = mock_client.capture_ai.call_args_list[0][1] assert ( span_props["properties"]["$ai_trace_id"] == span_props["properties"]["$ai_parent_id"] ) - generation_props = mock_client.capture.call_args_list[1][1] + generation_props = mock_client.capture_ai.call_args_list[1][1] assert ( generation_props["properties"]["$ai_trace_id"] == generation_props["properties"]["$ai_parent_id"] @@ -1521,9 +1533,9 @@ def span_3(_): chain = RunnableLambda(span_1) chain.invoke({}, config={"callbacks": callbacks}) - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - calls = mock_client.capture.call_args_list + calls = mock_client.capture_ai.call_args_list span_props_2 = calls[0][1]["properties"] span_props_1 = calls[1][1]["properties"] trace_props = calls[2][1]["properties"] @@ -1543,12 +1555,12 @@ def span(_): except ValueError: pass - assert mock_client.capture.call_count == 2 + assert mock_client.capture_ai.call_count == 2 assert ( - mock_client.capture.call_args_list[1][1]["properties"]["$ai_error"] + mock_client.capture_ai.call_args_list[1][1]["properties"]["$ai_error"] == "ValueError: test" ) - assert mock_client.capture.call_args_list[1][1]["properties"]["$ai_is_error"] + assert mock_client.capture_ai.call_args_list[1][1]["properties"]["$ai_is_error"] def test_captures_error_without_details_in_span(mock_client): @@ -1562,12 +1574,12 @@ def span(_): except ValueError: pass - assert mock_client.capture.call_count == 2 + assert mock_client.capture_ai.call_count == 2 assert ( - mock_client.capture.call_args_list[1][1]["properties"]["$ai_error"] + mock_client.capture_ai.call_args_list[1][1]["properties"]["$ai_error"] == "ValueError" ) - assert mock_client.capture.call_args_list[1][1]["properties"]["$ai_is_error"] + assert mock_client.capture_ai.call_args_list[1][1]["properties"]["$ai_is_error"] def test_openai_reasoning_tokens(mock_client): @@ -1596,9 +1608,9 @@ def test_openai_reasoning_tokens(mock_client): result = chain.invoke({}, config={"callbacks": callbacks}) assert result.content == "Let me think through this step by step..." - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - generation_args = mock_client.capture.call_args_list[1][1] + generation_args = mock_client.capture_ai.call_args_list[1][1] generation_props = generation_args["properties"] assert generation_args["event"] == "$ai_generation" @@ -1631,9 +1643,9 @@ def test_anthropic_cache_write_and_read_tokens(mock_client): result = chain.invoke({}, config={"callbacks": callbacks}) assert result.content == "I've analyzed the document and cached the context." - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - generation_args = mock_client.capture.call_args_list[1][1] + generation_args = mock_client.capture_ai.call_args_list[1][1] generation_props = generation_args["properties"] assert generation_args["event"] == "$ai_generation" @@ -1666,9 +1678,9 @@ def test_anthropic_cache_write_and_read_tokens(mock_client): result = chain.invoke({}, config={"callbacks": callbacks}) assert result.content == "Using cached analysis to provide quick response." - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - generation_args = mock_client.capture.call_args_list[1][1] + generation_args = mock_client.capture_ai.call_args_list[1][1] generation_props = generation_args["properties"] assert generation_args["event"] == "$ai_generation" @@ -1719,7 +1731,7 @@ def test_anthropic_provider_subtracts_cache_tokens(mock_client): cb._pop_run_and_capture_generation(run_id, None, response) - generation_args = mock_client.capture.call_args_list[0][1] + generation_args = mock_client.capture_ai.call_args_list[0][1] assert generation_args["properties"]["$ai_input_tokens"] == 400 # 1200 - 800 assert generation_args["properties"]["$ai_cache_read_input_tokens"] == 800 @@ -1766,7 +1778,7 @@ def test_chat_anthropic_invoke_does_not_subtract_cache_tokens_twice(mock_client) cb._pop_run_and_capture_generation(run_id, None, response) - props = mock_client.capture.call_args_list[0][1]["properties"] + props = mock_client.capture_ai.call_args_list[0][1]["properties"] assert props["$ai_input_tokens"] == 10 assert props["$ai_output_tokens"] == 7 assert props["$ai_cache_read_input_tokens"] == 1000 @@ -1805,7 +1817,7 @@ def test_claude_on_vertex_subtracts_cache_tokens(mock_client): cb._pop_run_and_capture_generation(run_id, None, response) - props = mock_client.capture.call_args_list[0][1]["properties"] + props = mock_client.capture_ai.call_args_list[0][1]["properties"] assert props["$ai_input_tokens"] == 10 assert props["$ai_cache_read_input_tokens"] == 1000 assert props["$ai_cache_creation_input_tokens"] == 100 @@ -1849,7 +1861,7 @@ def test_anthropic_provider_subtracts_cache_write_tokens(mock_client): cb._pop_run_and_capture_generation(run_id, None, response) - generation_args = mock_client.capture.call_args_list[0][1] + generation_args = mock_client.capture_ai.call_args_list[0][1] assert generation_args["properties"]["$ai_input_tokens"] == 200 # 1000 - 800 assert generation_args["properties"]["$ai_cache_creation_input_tokens"] == 800 @@ -2022,7 +2034,7 @@ def test_anthropic_provider_subtracts_both_cache_read_and_write_tokens(mock_clie cb._pop_run_and_capture_generation(run_id, None, response) - generation_args = mock_client.capture.call_args_list[0][1] + generation_args = mock_client.capture_ai.call_args_list[0][1] # 2000 - 800 (read) - 500 (write) = 700 assert generation_args["properties"]["$ai_input_tokens"] == 700 assert generation_args["properties"]["$ai_cache_read_input_tokens"] == 800 @@ -2058,9 +2070,9 @@ def test_openai_cache_read_tokens(mock_client): result = chain.invoke({}, config={"callbacks": callbacks}) assert result.content == "Response using cached prompt context." - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - generation_args = mock_client.capture.call_args_list[1][1] + generation_args = mock_client.capture_ai.call_args_list[1][1] generation_props = generation_args["properties"] assert generation_args["event"] == "$ai_generation" @@ -2102,9 +2114,9 @@ def test_openai_cache_creation_tokens(mock_client): result = chain.invoke({}, config={"callbacks": callbacks}) assert result.content == "Created cache for the prompt context." - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - generation_args = mock_client.capture.call_args_list[1][1] + generation_args = mock_client.capture_ai.call_args_list[1][1] generation_props = generation_args["properties"] assert generation_args["event"] == "$ai_generation" @@ -2144,9 +2156,9 @@ def test_combined_reasoning_and_cache_tokens(mock_client): result = chain.invoke({}, config={"callbacks": callbacks}) assert result.content == "Let me reason through this using cached context..." - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - generation_args = mock_client.capture.call_args_list[1][1] + generation_args = mock_client.capture_ai.call_args_list[1][1] generation_props = generation_args["properties"] assert generation_args["event"] == "$ai_generation" @@ -2166,7 +2178,7 @@ def test_openai_reasoning_tokens_o4_mini(mock_client): mock_client, trace_id="test-trace-id", distinct_id="test-distinct-id" ) model.invoke("what is the weather in sf", config={"callbacks": [cb]}) - call = mock_client.capture.call_args_list[0][1] + call = mock_client.capture_ai.call_args_list[0][1] assert call["properties"]["$ai_reasoning_tokens"] is not None assert call["properties"]["$ai_input_tokens"] is not None assert call["properties"]["$ai_output_tokens"] is not None @@ -2174,7 +2186,7 @@ def test_openai_reasoning_tokens_o4_mini(mock_client): def test_callback_handler_without_client(): """Test that CallbackHandler works properly when no PostHog client is passed.""" - with patch("posthog.ai.langchain.callbacks.setup") as mock_setup: + with patch("posthog.ai.utils.setup") as mock_setup: mock_client = mock_setup.return_value callbacks = CallbackHandler() @@ -2195,7 +2207,7 @@ def test_callback_handler_without_client(): assert result.content == "Bar" # Verify that the mock client was used for capturing events - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 def test_convert_message_to_dict_tool_calls(): @@ -2302,8 +2314,8 @@ def test_tool_definition(mock_client): parent_run_id=None, ) - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == run_id @@ -2353,9 +2365,9 @@ def test_cache_read_tokens_subtraction_from_input_tokens(mock_client): result = chain.invoke({}, config={"callbacks": callbacks}) assert result.content == "Response using cached prompt context." - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - generation_args = mock_client.capture.call_args_list[1][1] + generation_args = mock_client.capture_ai.call_args_list[1][1] generation_props = generation_args["properties"] assert generation_args["event"] == "$ai_generation" @@ -2395,9 +2407,9 @@ def test_cache_read_tokens_subtraction_prevents_negative(mock_client): result = chain.invoke({}, config={"callbacks": callbacks}) assert result.content == "Response with edge case token counts." - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - generation_args = mock_client.capture.call_args_list[1][1] + generation_args = mock_client.capture_ai.call_args_list[1][1] generation_props = generation_args["properties"] assert generation_args["event"] == "$ai_generation" @@ -2436,9 +2448,9 @@ def test_no_cache_read_tokens_no_subtraction(mock_client): result = chain.invoke({}, config={"callbacks": callbacks}) assert result.content == "Response without cache." - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - generation_args = mock_client.capture.call_args_list[1][1] + generation_args = mock_client.capture_ai.call_args_list[1][1] generation_props = generation_args["properties"] assert generation_args["event"] == "$ai_generation" @@ -2475,9 +2487,9 @@ def test_zero_input_tokens_with_cache_read(mock_client): result = chain.invoke({}, config={"callbacks": callbacks}) assert result.content == "Response." - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - generation_args = mock_client.capture.call_args_list[1][1] + generation_args = mock_client.capture_ai.call_args_list[1][1] generation_props = generation_args["properties"] assert generation_args["event"] == "$ai_generation" @@ -2516,9 +2528,9 @@ def test_non_anthropic_cache_write_tokens_not_subtracted_from_input(mock_client) result = chain.invoke({}, config={"callbacks": callbacks}) assert result.content == "Creating cache." - assert mock_client.capture.call_count == 3 + assert mock_client.capture_ai.call_count == 3 - generation_args = mock_client.capture.call_args_list[1][1] + generation_args = mock_client.capture_ai.call_args_list[1][1] generation_props = generation_args["properties"] assert generation_args["event"] == "$ai_generation" @@ -2567,8 +2579,8 @@ def test_agent_action_and_finish_imports(): callbacks.on_agent_finish(finish, run_id=run_id, parent_run_id=parent_run_id) # Verify capture was called - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] assert call_args["event"] == "$ai_span" @@ -2675,8 +2687,8 @@ def test_billable_property_in_generation_event(mock_client): parent_run_id=None, ) - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["event"] == "$ai_generation" @@ -2695,7 +2707,7 @@ def test_billable_defaults_to_false_in_event(mock_client): chain.invoke({}, config={"callbacks": callbacks}) generation_call = None - for call in mock_client.capture.call_args_list: + for call in mock_client.capture_ai.call_args_list: if call[1]["event"] == "$ai_generation": generation_call = call break @@ -2739,8 +2751,8 @@ def test_billable_with_real_chain(mock_client): parent_run_id=None, ) - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["event"] == "$ai_generation" @@ -2798,7 +2810,7 @@ def failing_span(_): # Find the span event (should have $ai_is_error=True) span_calls = [ call - for call in mock_client.capture.call_args_list + for call in mock_client.capture_ai.call_args_list if call[1].get("properties", {}).get("$ai_is_error") is True ] assert len(span_calls) >= 1 @@ -2810,7 +2822,7 @@ def failing_span(_): def test_exception_autocapture_absent_on_client_still_sends_the_span(): """A client without the autocapture setting, such as AsyncPosthog, still gets the failed span.""" - mock_client = MagicMock(spec=["capture", "capture_exception", "privacy_mode"]) + mock_client = MagicMock(spec=["capture_ai", "capture_exception", "privacy_mode"]) mock_client.privacy_mode = False def failing_span(_): @@ -2821,8 +2833,8 @@ def failing_span(_): RunnableLambda(failing_span).invoke({}, config={"callbacks": callbacks}) assert mock_client.capture_exception.call_count == 0 - assert mock_client.capture.call_count == 1 - span_props = mock_client.capture.call_args[1]["properties"] + assert mock_client.capture_ai.call_count == 1 + span_props = mock_client.capture_ai.call_args[1]["properties"] assert span_props["$ai_is_error"] is True assert span_props["$ai_error"] == "ValueError: test error" assert "$exception_event_id" not in span_props @@ -2861,7 +2873,7 @@ def failing_span(_): # But the span event should still have error info span_calls = [ call - for call in mock_client.capture.call_args_list + for call in mock_client.capture_ai.call_args_list if call[1].get("properties", {}).get("$ai_is_error") is True ] assert len(span_calls) >= 1 @@ -2899,7 +2911,7 @@ def test_exception_autocapture_on_llm_generation_error(mock_client): # Verify the generation event has $exception_event_id generation_calls = [ call - for call in mock_client.capture.call_args_list + for call in mock_client.capture_ai.call_args_list if call[1].get("event") == "$ai_generation" ] assert len(generation_calls) == 1 @@ -2909,6 +2921,53 @@ def test_exception_autocapture_on_llm_generation_error(mock_client): assert gen_props["$ai_is_error"] is True +@pytest.mark.parametrize( + "distinct_id, handler_options, run_options, expected_options", + [ + # No user: person processing stays off, as on the AI event. + (None, {}, None, {"process_person_profile": False}), + ( + None, + {"process_person_profile": True, "cookieless_mode": True}, + None, + {"process_person_profile": False, "cookieless_mode": True}, + ), + # A user: the options are sent as set, the handler's winning over the run's. + ("user-123", {}, None, None), + ( + "user-123", + {"cookieless_mode": True}, + {"cookieless_mode": False, "product_tour_id": "tour-1"}, + {"cookieless_mode": True, "product_tour_id": "tour-1"}, + ), + ], +) +def test_exception_autocapture_sends_ai_event_options( + distinct_id, handler_options, run_options, expected_options +): + """The `$exception` event carries the same options as its generation.""" + mock_client = MagicMock() + mock_client.privacy_mode = False + mock_client.enable_exception_autocapture = True + mock_client.capture_exception.return_value = "exception-uuid-opt" + + callbacks = CallbackHandler( + mock_client, distinct_id=distinct_id, options=handler_options + ) + run_id = uuid.uuid4() + metadata = {"posthog_options": run_options} if run_options is not None else None + callbacks.on_llm_start( + serialized={"kwargs": {"openai_api_base": "https://api.openai.com"}}, + prompts=["Hello"], + run_id=run_id, + metadata=metadata, + ) + callbacks.on_llm_error(Exception("boom"), run_id=run_id) + + assert mock_client.capture_exception.call_count == 1 + assert mock_client.capture_exception.call_args[1].get("options") == expected_options + + def test_exception_autocapture_passes_ai_properties_to_exception(): """Test that AI properties are passed to the exception event.""" mock_client = MagicMock() @@ -2973,7 +3032,7 @@ def failing_span(_): # Span event should NOT have $exception_event_id span_calls = [ call - for call in mock_client.capture.call_args_list + for call in mock_client.capture_ai.call_args_list if call[1].get("properties", {}).get("$ai_is_error") is True ] assert len(span_calls) >= 1 @@ -2982,20 +3041,6 @@ def failing_span(_): assert "$exception_event_id" not in span_props -def test_ai_lane_client_routes_through_capture_ai(mock_client): - prompt = ChatPromptTemplate.from_messages([("user", "Who won the world series?")]) - model = FakeMessagesListChatModel(responses=[AIMessage(content="The Dodgers.")]) - mock_client.enable_full_ai_capture = True - callbacks = [CallbackHandler(mock_client)] - - (prompt | model).invoke({}, config={"callbacks": callbacks}) - - mock_client.capture.assert_not_called() - events = [c[1]["event"] for c in mock_client.capture_ai.call_args_list] - assert "$ai_generation" in events - assert "$ai_trace" in events - - def test_served_service_tier_merges_into_model_parameters(mock_client): from langchain_core.messages import AIMessage from langchain_core.outputs import ChatGeneration, LLMResult @@ -3016,7 +3061,7 @@ def test_served_service_tier_merges_into_model_parameters(mock_client): cb._pop_run_and_capture_generation(run_id, None, response) - props = mock_client.capture.call_args.kwargs["properties"] + props = mock_client.capture_ai.call_args.kwargs["properties"] assert props["$ai_model_parameters"]["service_tier"] == "flex" assert props["$ai_model_parameters"]["temperature"] == 0.5 assert props["$ai_service_tier"] == "flex" @@ -3073,7 +3118,7 @@ def test_stop_reason_resolution( cb._pop_run_and_capture_generation(run_id, None, response) - props = mock_client.capture.call_args.kwargs["properties"] + props = mock_client.capture_ai.call_args.kwargs["properties"] assert props.get("$ai_stop_reason") == expected @@ -3124,7 +3169,7 @@ def test_web_search_count(mock_client, server_tool_use, expected): cb._pop_run_and_capture_generation(run_id, None, response) - props = mock_client.capture.call_args.kwargs["properties"] + props = mock_client.capture_ai.call_args.kwargs["properties"] assert props.get("$ai_web_search_count") == expected @@ -3185,5 +3230,73 @@ def test_an_error_event_records_an_integer_status(self): callback._pop_run_and_capture_generation(run_id, None, error) - properties = client.capture.call_args_list[0][1]["properties"] + properties = client.capture_ai.call_args_list[0][1]["properties"] assert properties["$ai_http_status"] == 0 + + +def _invoke_fake_chain(handler, metadata=None): + prompt = ChatPromptTemplate.from_messages([("user", "Foo")]) + chain = prompt | FakeMessagesListChatModel(responses=[AIMessage(content="Bar")]) + config = {"callbacks": [handler]} + if metadata is not None: + config["metadata"] = metadata + chain.invoke({}, config=config) + + +@pytest.mark.parametrize( + "case", POSTHOG_OPTIONS_CASES, ids=[case[0] for case in POSTHOG_OPTIONS_CASES] +) +def test_handler_options_reach_every_event(mock_client, caplog, case): + _, distinct_id, options, expected, warns = case + + with caplog.at_level(logging.WARNING, logger="posthog"): + _invoke_fake_chain( + CallbackHandler(mock_client, distinct_id=distinct_id, options=options) + ) + + calls = mock_client.capture_ai.call_args_list + assert [call.kwargs["event"] for call in calls] == [ + "$ai_span", + "$ai_generation", + "$ai_trace", + ] + for call in calls: + assert_captured_options(call.kwargs, expected, warns, caplog) + + +def test_run_metadata_posthog_options_reach_the_generation(mock_client): + _invoke_fake_chain( + CallbackHandler( + mock_client, distinct_id="user-1", options={"cookieless_mode": True} + ), + metadata={ + "posthog_options": { + "cookieless_mode": False, + "disable_skew_correction": True, + } + }, + ) + + options_by_event = { + call.kwargs["event"]: call.kwargs["options"] + for call in mock_client.capture_ai.call_args_list + } + # The handler's options win over the run's, like its properties. + assert options_by_event == { + "$ai_span": {"cookieless_mode": True}, + "$ai_generation": {"cookieless_mode": True, "disable_skew_correction": True}, + "$ai_trace": {"cookieless_mode": True}, + } + + +def test_non_dict_run_metadata_posthog_options_are_ignored(mock_client, caplog): + with caplog.at_level(logging.WARNING, logger="posthog"): + _invoke_fake_chain( + CallbackHandler(mock_client), + metadata={"posthog_options": "cookieless_mode"}, + ) + + generation = mock_client.capture_ai.call_args_list[1].kwargs + assert generation["event"] == "$ai_generation" + assert generation["options"] == {"process_person_profile": False} + assert "posthog_options must be a dict" in caplog.text diff --git a/posthog/test/ai/langchain/test_middleware.py b/posthog/test/ai/langchain/test_middleware.py index f01dd91c2..609d9e882 100644 --- a/posthog/test/ai/langchain/test_middleware.py +++ b/posthog/test/ai/langchain/test_middleware.py @@ -121,7 +121,7 @@ def _client() -> MagicMock: def _events(client: MagicMock) -> list[dict[str, Any]]: - return [call.kwargs for call in client.capture.call_args_list] + return [call.kwargs for call in client.capture_ai.call_args_list] def _event(client: MagicMock, event_name: str) -> dict[str, Any]: @@ -199,6 +199,7 @@ def test_instruments_sync_agent_model_and_tool_loop() -> None: trace_id="trace-id", properties={"environment": "test"}, groups={"company": "posthog"}, + options={"cookieless_mode": True}, ) ], ) @@ -219,6 +220,7 @@ def test_instruments_sync_agent_model_and_tool_loop() -> None: assert trace["groups"] == {"company": "posthog"} assert all(event["properties"]["$ai_trace_id"] == "trace-id" for event in events) assert all(event["properties"]["environment"] == "test" for event in events) + assert all(event["options"] == {"cookieless_mode": True} for event in events) assert all( event["properties"].get("$ai_parent_id") == trace["properties"]["$ai_span_id"] for event in events[:-1] @@ -353,7 +355,7 @@ async def test_async_hooks_do_not_capture_on_the_event_loop_thread() -> None: client.sync_mode = True event_loop_thread = threading.get_ident() capture_threads: list[int] = [] - client.capture.side_effect = lambda **_: capture_threads.append( + client.capture_ai.side_effect = lambda **_: capture_threads.append( threading.get_ident() ) middleware = PostHogMiddleware(client) @@ -841,7 +843,7 @@ def test_privacy_mode_redacts_agent_and_model_content() -> None: def test_capture_failure_never_changes_agent_result() -> None: client = _client() - client.capture.side_effect = RuntimeError("telemetry unavailable") + client.capture_ai.side_effect = RuntimeError("telemetry unavailable") middleware = PostHogMiddleware(client) state = _middleware_state(middleware) request = _model_request(StubAgentModel(responses=[]), state) diff --git a/posthog/test/ai/openai/test_async_parity.py b/posthog/test/ai/openai/test_async_parity.py index 850b2a885..8a96bfec8 100644 --- a/posthog/test/ai/openai/test_async_parity.py +++ b/posthog/test/ai/openai/test_async_parity.py @@ -46,7 +46,7 @@ def _sync_props(mock_client, chunks): posthog_distinct_id="test-id", ) ) - return mock_client.capture.call_args[1]["properties"] + return mock_client.capture_ai.call_args[1]["properties"] async def _async_props(mock_client, chunks): @@ -68,7 +68,7 @@ async def it(): ) async for _ in stream: pass - return mock_client.capture.call_args[1]["properties"] + return mock_client.capture_ai.call_args[1]["properties"] @pytest.mark.asyncio @@ -76,7 +76,7 @@ async def test_async_streaming_emits_the_same_properties_as_sync( mock_client, streaming_tool_call_chunks ): sync_props = _sync_props(mock_client, streaming_tool_call_chunks) - mock_client.capture.reset_mock() + mock_client.capture_ai.reset_mock() async_props = await _async_props(mock_client, streaming_tool_call_chunks) # Guard: if the sync side stopped emitting these, the comparison below is vacuous. @@ -120,7 +120,7 @@ async def test_responses_streaming_properties_have_sync_async_parity(mock_client ): client = OpenAI(api_key="test-key", posthog_client=mock_client) list(client.responses.create(**request)) - sync_props = mock_client.capture.call_args.kwargs["properties"] + sync_props = mock_client.capture_ai.call_args.kwargs["properties"] async def create(self, **kwargs): async def chunks(): @@ -128,13 +128,13 @@ async def chunks(): return chunks() - mock_client.capture.reset_mock() + mock_client.capture_ai.reset_mock() with patch("openai.resources.responses.AsyncResponses.create", new=create): client = AsyncOpenAI(api_key="test-key", posthog_client=mock_client) stream = await client.responses.create(**request) async for _ in stream: pass - async_props = mock_client.capture.call_args.kwargs["properties"] + async_props = mock_client.capture_ai.call_args.kwargs["properties"] sync_without_latency = {k: v for k, v in sync_props.items() if k != "$ai_latency"} async_without_latency = {k: v for k, v in async_props.items() if k != "$ai_latency"} @@ -167,15 +167,15 @@ async def test_embedding_telemetry_has_sync_async_parity(mock_client): client = OpenAI(api_key="test-key", posthog_client=mock_client) assert client.embeddings.create(**request) is response sync_create.assert_called_once_with(**provider_request) - sync_capture = mock_client.capture.call_args + sync_capture = mock_client.capture_ai.call_args async_create = AsyncMock(return_value=response) - mock_client.capture.reset_mock() + mock_client.capture_ai.reset_mock() with patch("openai.resources.embeddings.AsyncEmbeddings.create", new=async_create): client = AsyncOpenAI(api_key="test-key", posthog_client=mock_client) assert await client.embeddings.create(**request) is response async_create.assert_awaited_once_with(**provider_request) - async_capture = mock_client.capture.call_args + async_capture = mock_client.capture_ai.call_args sync_props = sync_capture.kwargs["properties"] async_props = async_capture.kwargs["properties"] @@ -186,7 +186,8 @@ async def test_embedding_telemetry_has_sync_async_parity(mock_client): assert async_props["$ai_input"] is None assert async_props["$ai_input_tokens"] == 12 assert async_props["$ai_provider"] == "azure" - assert async_props["$process_person_profile"] is False + assert async_capture.kwargs["options"] == sync_capture.kwargs["options"] + assert async_capture.kwargs["options"] == {"process_person_profile": False} assert async_capture.kwargs["distinct_id"] == "shared-trace" assert async_capture.kwargs["groups"] == {"company": "test-company"} @@ -208,5 +209,5 @@ def test_sync_stream_close_after_early_exit_captures_partial_state( assert next(stream) == streaming_tool_call_chunks[0] stream.close() - assert mock_client.capture.call_count == 1 - assert mock_client.capture.call_args.kwargs["properties"]["$ai_model"] == "gpt-4" + assert mock_client.capture_ai.call_count == 1 + assert mock_client.capture_ai.call_args.kwargs["properties"]["$ai_model"] == "gpt-4" diff --git a/posthog/test/ai/openai/test_openai.py b/posthog/test/ai/openai/test_openai.py index edbe3c9de..0e6dde342 100644 --- a/posthog/test/ai/openai/test_openai.py +++ b/posthog/test/ai/openai/test_openai.py @@ -2,7 +2,7 @@ import logging import os import time -from unittest.mock import AsyncMock, patch +from unittest.mock import AsyncMock, MagicMock, patch import pytest @@ -38,9 +38,12 @@ from posthog.ai.openai.openai_async import AsyncOpenAI from posthog.ai.openai.wrapper_utils import reset_fallback_warnings from posthog.test.ai.utils import ( + POSTHOG_OPTIONS_CASES, RecordingAsyncStream, RecordingStream, + assert_captured_options, make_response_usage, + posthog_call_kwargs, ) OPENAI_AVAILABLE = True @@ -398,9 +401,9 @@ def test_basic_completion(mock_client, mock_openai_response): ) assert response == mock_openai_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -445,9 +448,9 @@ def test_embeddings(mock_client, mock_embedding_response): ) assert response == mock_embedding_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -501,9 +504,9 @@ def test_embeddings_error(mock_client): posthog_distinct_id="test-id", ) - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" assert call_args["event"] == "$ai_embedding" @@ -529,9 +532,9 @@ def test_groups(mock_client, mock_openai_response): ) assert response == mock_openai_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] assert call_args["groups"] == {"company": "test_company"} @@ -550,9 +553,9 @@ def test_privacy_mode_local(mock_client, mock_openai_response): ) assert response == mock_openai_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] is None assert props["$ai_output_choices"] is None @@ -573,9 +576,9 @@ def test_privacy_mode_global(mock_client, mock_openai_response): ) assert response == mock_openai_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input"] is None assert props["$ai_output_choices"] is None @@ -592,9 +595,9 @@ def test_error(mock_client, mock_openai_response): model="gpt-4", messages=[{"role": "user", "content": "Hello"}] ) - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_is_error"] is True assert props["$ai_error"] == "Test error" @@ -614,9 +617,9 @@ def test_cached_tokens(mock_client, mock_openai_response_with_cached_tokens): ) assert response == mock_openai_response_with_cached_tokens - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -653,9 +656,9 @@ def test_null_token_details_do_not_crash( ) assert response == mock_openai_response_with_null_token_details - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_input_tokens"] == 20 @@ -689,9 +692,9 @@ def test_tool_calls(mock_client, mock_openai_response_with_tool_calls): ) assert response == mock_openai_response_with_tool_calls - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -760,9 +763,9 @@ def test_tool_calls_only_no_content(mock_client, mock_openai_response_tool_calls ) assert response == mock_openai_response_tool_calls_only - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -853,8 +856,8 @@ async def test_custom_tool_calls_are_captured(mock_client, is_async): response = client.chat.completions.create(**kwargs) assert response == completion - assert mock_client.capture.call_count == 1 - props = mock_client.capture.call_args[1]["properties"] + assert mock_client.capture_ai.call_count == 1 + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_output_choices"] == [ { "role": "assistant", @@ -901,9 +904,9 @@ def test_responses_api_tool_calls(mock_client, mock_responses_api_with_tool_call ) assert response == mock_responses_api_with_tool_calls - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -934,6 +937,25 @@ def test_responses_api_tool_calls(mock_client, mock_responses_api_with_tool_call assert props["$ai_http_status"] == 200 +def test_client_without_capture_ai_still_returns_the_provider_response( + mock_openai_response, caplog +): + ph_client = MagicMock(spec=["capture", "privacy_mode"]) + with patch( + "openai.resources.chat.completions.Completions.create", + return_value=mock_openai_response, + ): + with caplog.at_level(logging.ERROR, logger="posthog"): + client = OpenAI(api_key="test-key", posthog_client=ph_client) + response = client.chat.completions.create( + model="gpt-4", messages=[{"role": "user", "content": "Hello"}] + ) + + assert response == mock_openai_response + assert "capture_ai" in caplog.text + ph_client.capture.assert_not_called() + + def test_streaming_with_tool_calls(mock_client, streaming_tool_call_chunks): # Mock the create method to return our chunks with patch("openai.resources.chat.completions.Completions.create") as mock_create: @@ -970,9 +992,9 @@ def test_streaming_with_tool_calls(mock_client, streaming_tool_call_chunks): assert chunks == streaming_tool_call_chunks # Verify the capture was called with the right arguments - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -1046,9 +1068,9 @@ def test_responses_api(mock_client, mock_openai_response_with_responses_api): posthog_properties={"foo": "bar"}, ) assert response == mock_openai_response_with_responses_api - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -1111,9 +1133,9 @@ def test_responses_parse(mock_client, mock_parsed_response): ) assert response == mock_parsed_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -1163,9 +1185,9 @@ def test_chat_completions_parse(mock_client, mock_openai_response): assert response == mock_openai_response assert mock_parse.call_count == 1 assert "posthog_distinct_id" not in mock_parse.call_args.kwargs - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -1204,9 +1226,9 @@ async def test_async_chat_completions_parse(mock_client, mock_openai_response): assert response == mock_openai_response mock_parse.assert_awaited_once() assert "posthog_distinct_id" not in mock_parse.call_args.kwargs - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -1329,9 +1351,9 @@ def mock_streaming_response(**kwargs): assert "stream_options" not in captured_kwargs # Verify capture was called - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify tokens are captured correctly from response.usage (not 0) @@ -1394,8 +1416,8 @@ async def chunk_iterable(): assert len(chunks) == len(streaming_tool_call_chunks) assert chunks == streaming_tool_call_chunks - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -1462,8 +1484,8 @@ async def chunk_iterable(): kwargs = captured_kwargs["kwargs"] assert "stream_options" not in kwargs - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -1489,9 +1511,9 @@ async def test_async_embeddings_error(mock_client): posthog_distinct_id="test-id", ) - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["event"] == "$ai_embedding" assert props["$ai_is_error"] is True @@ -1551,9 +1573,9 @@ async def test_async_embeddings_create(mock_client, mock_embedding_response): assert response == mock_embedding_response assert mock_create.await_count == 1 - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -1602,9 +1624,9 @@ def test_tool_definition(mock_client, mock_openai_response): ) assert response == mock_openai_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["distinct_id"] == "test-id" @@ -1666,9 +1688,9 @@ def __init__(self): ) assert response == mock_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify web search count is detected (binary detection) @@ -1725,9 +1747,9 @@ def mock_create_call(**kwargs): ) assert result == mock_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify exact web search count @@ -1812,9 +1834,9 @@ def test_streaming_with_web_search(mock_client, streaming_web_search_chunks): # Verify the chunks were returned correctly assert len(chunks) == 3 - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify web search count is captured (binary detection = 1) @@ -1848,9 +1870,9 @@ def test_streaming_with_web_search_on_non_usage_chunk( # Verify the chunks were returned correctly assert len(chunks) == 3 - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify web search count is captured even though citations were on first chunk @@ -1904,9 +1926,9 @@ async def mock_create(self, **kwargs): ) assert response == mock_response - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify web search count is captured (binary detection = 1) @@ -1953,9 +1975,9 @@ async def chunk_iterable(): # Verify the chunks were returned correctly assert len(chunks) == 3 - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Verify web search count is captured (binary detection = 1) @@ -2020,8 +2042,8 @@ def test_streaming_chat_extracts_model_from_chunk_when_not_in_kwargs(mock_client # Consume the generator list(response_generator) - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Model should be extracted from chunk, not kwargs @@ -2067,7 +2089,7 @@ def chunk(index, content=None, finish_reason=None): ) ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] # The same shape a non-streamed n=2 completion is captured with. assert props["$ai_output_choices"] == [ { @@ -2118,7 +2140,7 @@ def test_streaming_chat_prefers_kwargs_model_over_chunk_model(mock_client): list(response_generator) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # kwargs model should take precedence @@ -2166,7 +2188,7 @@ def test_streaming_responses_api_extracts_model_from_response_object(mock_client list(response_generator) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Model should be extracted from chunk.response.model @@ -2240,7 +2262,7 @@ def test_streaming_responses_api_captures_usage_and_output_when_incomplete( ) list(response_generator) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_stop_reason"] == "max_output_tokens" assert props["$ai_input_tokens"] == 20 assert props["$ai_output_tokens"] == 16 @@ -2290,7 +2312,7 @@ def test_non_streaming_extracts_model_from_response(mock_client): ) assert response == mock_response - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Model should be extracted from response.model @@ -2350,7 +2372,7 @@ def test_non_streaming_responses_api_extracts_model_from_response(mock_client): ) assert response == mock_response - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Model should be extracted from response.model @@ -2396,7 +2418,7 @@ def test_non_streaming_returns_none_when_no_model(mock_client): posthog_distinct_id="test-id", ) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Should be None, NOT "unknown" (to avoid incorrect cost matching) @@ -2435,7 +2457,7 @@ def test_streaming_falls_back_to_unknown_when_no_model(mock_client): list(response_generator) - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] # Should fall back to "unknown" @@ -2488,7 +2510,7 @@ async def chunk_iterable(): async for _ in response_stream: pass - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_model"] == "gpt-4o-async-stored" @@ -2538,7 +2560,7 @@ async def chunk_iterable(): async for _ in response_stream: pass - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_model"] == "gpt-4o-mini-async-stored" @@ -2557,7 +2579,7 @@ def test_integration_stop_reason(mock_client): posthog_distinct_id="test-id", ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_stop_reason"] in ("stop", "length") assert props["$ai_provider"] == "openai" assert props["$ai_input_tokens"] > 0 @@ -2591,8 +2613,8 @@ async def mock_create(self, **kwargs): chunks.append(chunk) assert chunks == streaming_tool_call_chunks - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["event"] == "$ai_generation" assert props["$ai_provider"] == "openai" @@ -2626,7 +2648,7 @@ async def mock_create(self, **kwargs): received = [c async for c in stream] assert received == [chunk] - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 @pytest.mark.asyncio @@ -2657,7 +2679,7 @@ async def mock_create(self, **kwargs): break assert source.closed is True - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 def test_chat_streaming_supports_with_and_proxies_provider_stream( @@ -2685,8 +2707,8 @@ def test_chat_streaming_supports_with_and_proxies_provider_stream( assert chunks == streaming_tool_call_chunks assert source.closed is True - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert call_args["event"] == "$ai_generation" assert props["$ai_provider"] == "openai" @@ -2718,7 +2740,7 @@ def test_responses_streaming_supports_with_and_proxies_provider_stream(mock_clie assert received == [chunk] assert source.closed is True - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 def test_chat_streaming_early_exit_closes_provider_stream( @@ -2745,7 +2767,7 @@ def test_chat_streaming_early_exit_closes_provider_stream( break assert source.closed is True - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 def test_chat_streaming_close_closes_provider_stream( @@ -2770,25 +2792,7 @@ def test_chat_streaming_close_closes_provider_stream( response.close() assert source.closed is True - assert mock_client.capture.call_count == 1 - - -def test_ai_lane_client_routes_through_capture_ai(mock_client, mock_openai_response): - mock_client.enable_full_ai_capture = True - with patch( - "openai.resources.chat.completions.Completions.create", - return_value=mock_openai_response, - ): - client = OpenAI(api_key="test-key", posthog_client=mock_client) - client.chat.completions.create( - model="gpt-4", - messages=[{"role": "user", "content": "Hello"}], - posthog_distinct_id="test-id", - ) - - mock_client.capture.assert_not_called() assert mock_client.capture_ai.call_count == 1 - assert mock_client.capture_ai.call_args[1]["event"] == "$ai_generation" def test_multimodal_client_skips_media_redaction(mock_client, mock_openai_response): @@ -2851,8 +2855,8 @@ def test_provider_override_chat_completions(mock_client, mock_openai_response): # The override must never reach the underlying OpenAI request. assert "posthog_provider_override" not in mock_create.call_args.kwargs - assert mock_client.capture.call_count == 1 - call_args = mock_client.capture.call_args[1] + assert mock_client.capture_ai.call_count == 1 + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_provider"] == "deepseek" @@ -2877,8 +2881,8 @@ def test_provider_override_omitted_defaults_to_openai( posthog_distinct_id="test-id", ) - assert mock_client.capture.call_count == 1 - props = mock_client.capture.call_args[1]["properties"] + assert mock_client.capture_ai.call_count == 1 + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_provider"] == "openai" @@ -2919,8 +2923,8 @@ def test_provider_override_streaming_chat_completions(mock_client): list(response_generator) assert "posthog_provider_override" not in mock_create.call_args.kwargs - assert mock_client.capture.call_count == 1 - props = mock_client.capture.call_args[1]["properties"] + assert mock_client.capture_ai.call_count == 1 + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_provider"] == "groq" assert props["$ai_model"] == "gpt-4" @@ -2942,9 +2946,9 @@ def test_provider_override_responses_api( assert response == mock_openai_response_with_responses_api assert "posthog_provider_override" not in mock_create.call_args.kwargs - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_provider"] == "xai" assert props["$ai_model"] == "gpt-4o-mini" @@ -2965,9 +2969,9 @@ def test_provider_override_embeddings(mock_client, mock_embedding_response): assert response == mock_embedding_response assert "posthog_provider_override" not in mock_create.call_args.kwargs - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_provider"] == "mistral" assert props["$ai_model"] == "text-embedding-3-small" @@ -2990,9 +2994,9 @@ def test_provider_override_chat_completions_parse(mock_client, mock_openai_respo assert response == mock_openai_response assert mock_parse.call_count == 1 assert "posthog_provider_override" not in mock_parse.call_args.kwargs - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - call_args = mock_client.capture.call_args[1] + call_args = mock_client.capture_ai.call_args[1] props = call_args["properties"] assert props["$ai_provider"] == "cerebras" assert props["$ai_model"] == "gpt-4" @@ -3019,9 +3023,9 @@ async def test_async_provider_override_chat_completions( assert response == mock_openai_response mock_create.assert_awaited_once() assert "posthog_provider_override" not in mock_create.call_args.kwargs - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_provider"] == "together" assert props["$ai_model"] == "gpt-4" @@ -3045,8 +3049,8 @@ async def test_async_provider_override_omitted_defaults_to_openai( posthog_distinct_id="test-id", ) - assert mock_client.capture.call_count == 1 - props = mock_client.capture.call_args[1]["properties"] + assert mock_client.capture_ai.call_count == 1 + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_provider"] == "openai" @@ -3085,8 +3089,8 @@ async def chunk_iterable(): assert "posthog_provider_override" not in captured_kwargs["kwargs"] assert len(chunks) == len(streaming_tool_call_chunks) - assert mock_client.capture.call_count == 1 - props = mock_client.capture.call_args[1]["properties"] + assert mock_client.capture_ai.call_count == 1 + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_provider"] == "fireworks" assert props["$ai_model"] == "gpt-4" @@ -3108,9 +3112,9 @@ async def test_async_provider_override_embeddings(mock_client, mock_embedding_re assert response == mock_embedding_response assert mock_create.await_count == 1 assert "posthog_provider_override" not in mock_create.call_args.kwargs - assert mock_client.capture.call_count == 1 + assert mock_client.capture_ai.call_count == 1 - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_provider"] == "perplexity" assert props["$ai_model"] == "text-embedding-3-small" @@ -3130,7 +3134,7 @@ def test_served_service_tier_lands_in_model_parameters( posthog_distinct_id="test-id", ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_model_parameters"]["service_tier"] == "flex" assert props["$ai_service_tier"] == "flex" @@ -3147,7 +3151,7 @@ def test_response_without_service_tier_omits_it(mock_client, mock_openai_respons posthog_distinct_id="test-id", ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert "service_tier" not in props["$ai_model_parameters"] assert "$ai_service_tier" not in props @@ -3169,3 +3173,271 @@ def test_streaming_state_tracks_served_service_tier(): SimpleNamespace(response=SimpleNamespace(service_tier="flex"), type="other") ) assert responses_state.service_tier == "flex" + + +def _options_chat_completion(): + return ChatCompletion( + id="test", + model="gpt-4", + object="chat.completion", + created=1741476542, + choices=[ + Choice( + finish_reason="stop", + index=0, + message=ChatCompletionMessage(content="Hi", role="assistant"), + ) + ], + usage=CompletionUsage(completion_tokens=1, prompt_tokens=2, total_tokens=3), + ) + + +def _options_chat_chunks(): + return [ + ChatCompletionChunk( + id="chunk", + model="gpt-4", + object="chat.completion.chunk", + created=1741476542, + choices=[ + ChoiceChunk( + index=0, delta=ChoiceDelta(content="Hi"), finish_reason="stop" + ) + ], + usage=CompletionUsage(completion_tokens=1, prompt_tokens=2, total_tokens=3), + ) + ] + + +def _options_response(): + return Response( + id="test", + model="gpt-4o-mini", + object="response", + created_at=1741476542, + status="completed", + error=None, + incomplete_details=None, + instructions=None, + max_output_tokens=None, + tools=[], + tool_choice="auto", + output=[], + parallel_tool_calls=True, + previous_response_id=None, + usage=make_response_usage(input_tokens=2, output_tokens=1, total_tokens=3), + user=None, + metadata={}, + ) + + +def _options_response_chunks(): + chunk = MagicMock() + chunk.type = "response.completed" + chunk.response.usage = make_response_usage( + input_tokens=2, output_tokens=1, total_tokens=3 + ) + chunk.response.output = [] + return [chunk] + + +def _options_embedding(): + return CreateEmbeddingResponse( + data=[Embedding(embedding=[0.1], index=0, object="embedding")], + model="text-embedding-3-small", + object="list", + usage=Usage(prompt_tokens=2, total_tokens=2), + ) + + +_CHAT_KWARGS = {"model": "gpt-4", "messages": [{"role": "user", "content": "Hi"}]} +_RESPONSES_KWARGS = {"model": "gpt-4o-mini", "input": "Hi"} + +# id, provider module, provider class, method, wrapper accessor, call kwargs, +# response factory, whether the call streams +OPENAI_OPTIONS_CALLS = [ + ( + "chat_create", + "openai.resources.chat.completions", + "Completions", + "create", + lambda client: client.chat.completions.create, + _CHAT_KWARGS, + _options_chat_completion, + False, + ), + ( + "chat_create_stream", + "openai.resources.chat.completions", + "Completions", + "create", + lambda client: client.chat.completions.create, + {**_CHAT_KWARGS, "stream": True}, + _options_chat_chunks, + True, + ), + ( + "chat_parse", + "openai.resources.chat.completions", + "Completions", + "parse", + lambda client: client.chat.completions.parse, + _CHAT_KWARGS, + _options_chat_completion, + False, + ), + ( + "beta_chat_parse", + "openai.resources.chat.completions", + "Completions", + "parse", + lambda client: client.beta.chat.completions.parse, + _CHAT_KWARGS, + _options_chat_completion, + False, + ), + ( + "responses_create", + "openai.resources.responses", + "Responses", + "create", + lambda client: client.responses.create, + _RESPONSES_KWARGS, + _options_response, + False, + ), + ( + "responses_create_stream", + "openai.resources.responses", + "Responses", + "create", + lambda client: client.responses.create, + {**_RESPONSES_KWARGS, "stream": True}, + _options_response_chunks, + True, + ), + ( + "responses_parse", + "openai.resources.responses", + "Responses", + "parse", + lambda client: client.responses.parse, + _RESPONSES_KWARGS, + _options_response, + False, + ), + ( + "embeddings_create", + "openai.resources.embeddings", + "Embeddings", + "create", + lambda client: client.embeddings.create, + {"model": "text-embedding-3-small", "input": "Hi"}, + _options_embedding, + False, + ), +] + + +def _recording_provider_method(make_response, is_async, stream, provider_calls): + def respond(kwargs): + provider_calls.append(kwargs) + response = make_response() + if not stream: + return response + return RecordingAsyncStream(response) if is_async else RecordingStream(response) + + if is_async: + + async def async_method(self, **kwargs): + return respond(kwargs) + + return async_method + + def method(self, **kwargs): + return respond(kwargs) + + return method + + +@pytest.mark.parametrize( + "case", POSTHOG_OPTIONS_CASES, ids=[case[0] for case in POSTHOG_OPTIONS_CASES] +) +@pytest.mark.parametrize( + "call", OPENAI_OPTIONS_CALLS, ids=[call[0] for call in OPENAI_OPTIONS_CALLS] +) +@pytest.mark.parametrize("is_async", [False, True], ids=["sync", "async"]) +async def test_posthog_options_reach_capture_and_not_the_provider( + mock_client, caplog, is_async, call, case +): + _, module, class_name, method, accessor, call_kwargs, make_response, stream = call + _, distinct_id, posthog_options, expected, warns = case + provider_class = f"Async{class_name}" if is_async else class_name + provider_calls = [] + + with patch( + f"{module}.{provider_class}.{method}", + new=_recording_provider_method(make_response, is_async, stream, provider_calls), + ): + client_class = AsyncOpenAI if is_async else OpenAI + client = client_class(api_key="test-key", posthog_client=mock_client) + with caplog.at_level(logging.WARNING, logger="posthog"): + result = accessor(client)( + **call_kwargs, **posthog_call_kwargs(distinct_id, posthog_options) + ) + if is_async: + result = await result + if stream: + if is_async: + _ = [chunk async for chunk in result] + else: + list(result) + + assert len(provider_calls) == 1 + assert not any(key.startswith("posthog_") for key in provider_calls[0]) + assert mock_client.capture_ai.call_count == 1 + assert_captured_options( + mock_client.capture_ai.call_args.kwargs, expected, warns, caplog + ) + + +def test_posthog_options_beat_context_options_and_super_options(): + from posthog import new_context, set_context_option + from posthog.capture_event import _to_v1_event + from posthog.client import Client + + sent = [] + posthog_client = Client( + "phc_test", + send=False, + before_send=lambda msg: sent.append(msg) or msg, + super_options={"cookieless_mode": False, "disable_skew_correction": True}, + ) + + with patch( + "openai.resources.chat.completions.Completions.create", + return_value=_options_chat_completion(), + ): + client = OpenAI(api_key="test-key", posthog_client=posthog_client) + with new_context(): + set_context_option("cookieless_mode", False) + set_context_option("product_tour_id", "tour-1") + client.chat.completions.create( + **_CHAT_KWARGS, + posthog_distinct_id="user-1", + posthog_options={"cookieless_mode": True}, + ) + client.chat.completions.create(**_CHAT_KWARGS, posthog_distinct_id="user-1") + + assert [_to_v1_event(msg)["options"] for msg in sent] == [ + { + "cookieless_mode": True, + "product_tour_id": "tour-1", + "disable_skew_correction": True, + }, + { + "cookieless_mode": False, + "product_tour_id": "tour-1", + "disable_skew_correction": True, + }, + ] diff --git a/posthog/test/ai/openai_agents/test_processor.py b/posthog/test/ai/openai_agents/test_processor.py index 13f0c6c7a..7e70500c0 100644 --- a/posthog/test/ai/openai_agents/test_processor.py +++ b/posthog/test/ai/openai_agents/test_processor.py @@ -5,6 +5,8 @@ import pytest +from posthog.test.ai.utils import POSTHOG_OPTIONS_CASES, assert_captured_options + try: from agents.tracing.span_data import ( AgentSpanData, @@ -109,7 +111,7 @@ def test_on_trace_start_stores_metadata(self, processor, mock_client, mock_trace """Test that on_trace_start stores metadata but does not capture an event.""" processor.on_trace_start(mock_trace) - mock_client.capture.assert_not_called() + mock_client.capture_ai.assert_not_called() assert mock_trace.trace_id in processor._trace_metadata def test_on_trace_end_captures_ai_trace(self, processor, mock_client, mock_trace): @@ -117,8 +119,8 @@ def test_on_trace_end_captures_ai_trace(self, processor, mock_client, mock_trace processor.on_trace_start(mock_trace) processor.on_trace_end(mock_trace) - mock_client.capture.assert_called_once() - call_kwargs = mock_client.capture.call_args[1] + mock_client.capture_ai.assert_called_once() + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["event"] == "$ai_trace" assert call_kwargs["distinct_id"] == "test-user" @@ -137,27 +139,33 @@ def test_group_id_becomes_session_id( mock_span.span_data = GenerationSpanData(model="gpt-4o") processor.on_span_start(mock_span) processor.on_span_end(mock_span) - span_kwargs = mock_client.capture.call_args[1] + span_kwargs = mock_client.capture_ai.call_args[1] processor.on_trace_end(mock_trace) - trace_kwargs = mock_client.capture.call_args[1] + trace_kwargs = mock_client.capture_ai.call_args[1] assert span_kwargs["properties"]["$ai_session_id"] == "group_123" assert span_kwargs["properties"]["$ai_group_id"] == "group_123" assert trace_kwargs["properties"]["$ai_session_id"] == "group_123" assert trace_kwargs["properties"]["$ai_group_id"] == "group_123" - def test_personless_mode_when_no_distinct_id(self, mock_client, mock_trace): + @pytest.mark.parametrize( + "distinct_id", [None, "", " "], ids=["missing", "empty", "blank"] + ) + def test_personless_mode_when_no_distinct_id( + self, mock_client, mock_trace, distinct_id + ): """Test that trace events use personless mode when no distinct_id is provided.""" processor = PostHogTracingProcessor( client=mock_client, + distinct_id=distinct_id, ) processor.on_trace_start(mock_trace) processor.on_trace_end(mock_trace) - call_kwargs = mock_client.capture.call_args[1] - assert call_kwargs["properties"]["$process_person_profile"] is False + call_kwargs = mock_client.capture_ai.call_args[1] + assert call_kwargs["options"] == {"process_person_profile": False} # Should fallback to trace_id as the distinct_id assert call_kwargs["distinct_id"] == mock_trace.trace_id @@ -170,7 +178,7 @@ def test_personless_mode_for_spans_when_no_distinct_id( ) processor.on_trace_start(mock_trace) - mock_client.capture.reset_mock() + mock_client.capture_ai.reset_mock() span_data = GenerationSpanData(model="gpt-4o") mock_span.span_data = span_data @@ -178,8 +186,8 @@ def test_personless_mode_for_spans_when_no_distinct_id( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] - assert call_kwargs["properties"]["$process_person_profile"] is False + call_kwargs = mock_client.capture_ai.call_args[1] + assert call_kwargs["options"] == {"process_person_profile": False} assert call_kwargs["distinct_id"] == mock_span.trace_id def test_personless_mode_when_callable_returns_none( @@ -196,7 +204,7 @@ def resolver(trace): ) processor.on_trace_start(mock_trace) - mock_client.capture.reset_mock() + mock_client.capture_ai.reset_mock() span_data = GenerationSpanData(model="gpt-4o") mock_span.span_data = span_data @@ -204,8 +212,8 @@ def resolver(trace): processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] - assert call_kwargs["properties"]["$process_person_profile"] is False + call_kwargs = mock_client.capture_ai.call_args[1] + assert call_kwargs["options"] == {"process_person_profile": False} assert call_kwargs["distinct_id"] == mock_span.trace_id def test_person_profile_when_distinct_id_provided(self, mock_client, mock_trace): @@ -218,8 +226,8 @@ def test_person_profile_when_distinct_id_provided(self, mock_client, mock_trace) processor.on_trace_start(mock_trace) processor.on_trace_end(mock_trace) - call_kwargs = mock_client.capture.call_args[1] - assert "$process_person_profile" not in call_kwargs["properties"] + call_kwargs = mock_client.capture_ai.call_args[1] + assert "options" not in call_kwargs def test_on_trace_end_clears_metadata(self, processor, mock_client, mock_trace): """Test that on_trace_end clears stored trace metadata.""" @@ -229,7 +237,7 @@ def test_on_trace_end_clears_metadata(self, processor, mock_client, mock_trace): processor.on_trace_end(mock_trace) assert mock_trace.trace_id not in processor._trace_metadata # Also verify it captured the event - mock_client.capture.assert_called_once() + mock_client.capture_ai.assert_called_once() def test_on_span_start_tracks_time(self, processor, mock_span): """Test that on_span_start records start time.""" @@ -250,8 +258,8 @@ def test_generation_span_mapping(self, processor, mock_client, mock_span): processor.on_span_start(mock_span) processor.on_span_end(mock_span) - mock_client.capture.assert_called_once() - call_kwargs = mock_client.capture.call_args[1] + mock_client.capture_ai.assert_called_once() + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["event"] == "$ai_generation" assert call_kwargs["properties"]["$ai_trace_id"] == "trace_123456789" @@ -285,7 +293,7 @@ def test_generation_span_with_reasoning_tokens( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["properties"]["$ai_reasoning_tokens"] == 400 def test_generation_span_reads_nested_cache_tokens( @@ -316,7 +324,7 @@ def test_generation_span_reads_nested_cache_tokens( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_input_tokens"] == 100 assert props["$ai_cache_read_input_tokens"] == 60 assert props["$ai_output_tokens"] == 50 @@ -357,7 +365,7 @@ def test_response_span_reads_cache_tokens(self, processor, mock_client, mock_spa processor.on_span_start(mock_span) processor.on_span_end(mock_span) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_input_tokens"] == 100 assert props["$ai_cache_read_input_tokens"] == 60 assert props["$ai_output_tokens"] == 50 @@ -388,7 +396,7 @@ def test_cached_compatible_claude_usage_is_declared_inclusive(self): pass properties = next( call.kwargs["properties"] - for call in client.capture.call_args_list + for call in client.capture_ai.call_args_list if call.kwargs["event"] == "$ai_generation" ) assert properties["$ai_cache_read_input_tokens"] == 10318 @@ -414,7 +422,7 @@ def test_flat_cache_keys_keep_their_own_convention( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_cache_read_input_tokens"] == 60 assert "$ai_cache_reporting_exclusive" not in props @@ -441,7 +449,7 @@ def test_caller_cache_reporting_convention_takes_precedence( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_cache_read_input_tokens"] == 60 assert props["$ai_cache_reporting_exclusive"] is True @@ -457,7 +465,7 @@ def test_function_span_mapping(self, processor, mock_client, mock_span): processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["event"] == "$ai_span" assert call_kwargs["properties"]["$ai_span_name"] == "get_weather" @@ -480,7 +488,7 @@ def test_agent_span_mapping(self, processor, mock_client, mock_span): processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["event"] == "$ai_span" assert call_kwargs["properties"]["$ai_span_name"] == "CustomerServiceAgent" @@ -502,7 +510,7 @@ def test_handoff_span_mapping(self, processor, mock_client, mock_span): processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["event"] == "$ai_span" assert call_kwargs["properties"]["$ai_span_type"] == "handoff" @@ -524,7 +532,7 @@ def test_guardrail_span_mapping(self, processor, mock_client, mock_span): processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["event"] == "$ai_span" assert call_kwargs["properties"]["$ai_span_name"] == "ContentFilter" @@ -542,7 +550,7 @@ def test_custom_span_mapping(self, processor, mock_client, mock_span): processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["event"] == "$ai_span" assert call_kwargs["properties"]["$ai_span_name"] == "database_query" @@ -571,7 +579,7 @@ def test_privacy_mode_redacts_content(self, mock_client, mock_span): processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] # Content should be redacted assert call_kwargs["properties"]["$ai_input"] is None @@ -592,12 +600,12 @@ def test_client_privacy_mode_redacts_content(self, mock_client, mock_span): processor.on_span_start(mock_span) processor.on_span_end(mock_span) - properties = mock_client.capture.call_args.kwargs["properties"] + properties = mock_client.capture_ai.call_args.kwargs["properties"] assert properties["$ai_input"] is None assert properties["$ai_output_choices"] is None def test_client_without_privacy_mode_captures_content(self, mock_span): - client = SimpleNamespace(capture=MagicMock()) + client = SimpleNamespace(capture_ai=MagicMock()) processor = PostHogTracingProcessor(client=client) mock_span.span_data = GenerationSpanData( input=[{"role": "user", "content": "Visible message"}], @@ -607,7 +615,7 @@ def test_client_without_privacy_mode_captures_content(self, mock_span): processor.on_span_start(mock_span) processor.on_span_end(mock_span) - properties = client.capture.call_args.kwargs["properties"] + properties = client.capture_ai.call_args.kwargs["properties"] assert properties["$ai_input"] == [ {"role": "user", "content": "Visible message"} ] @@ -637,7 +645,7 @@ def test_generation_span_image_input_is_redacted( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] captured_input = call_kwargs["properties"]["$ai_input"] assert captured_input[0]["content"][0]["image_url"] == "[base64 image redacted]" @@ -691,7 +699,7 @@ def test_response_span_image_output_is_redacted( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] captured_output = call_kwargs["properties"]["$ai_output_choices"] assert ( captured_output[0]["content"][0]["image_url"] == "[base64 image redacted]" @@ -706,7 +714,7 @@ def test_error_handling_in_span(self, processor, mock_client, mock_span): processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["properties"]["$ai_is_error"] is True assert call_kwargs["properties"]["$ai_error"] == "Rate limit exceeded" @@ -724,7 +732,7 @@ def test_generation_span_includes_total_tokens( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["properties"]["$ai_total_tokens"] == 150 def test_error_type_categorization_model_behavior( @@ -741,7 +749,7 @@ def test_error_type_categorization_model_behavior( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["properties"]["$ai_error_type"] == "model_behavior_error" def test_error_type_categorization_user_error( @@ -755,7 +763,7 @@ def test_error_type_categorization_user_error( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["properties"]["$ai_error_type"] == "user_error" def test_error_type_categorization_input_guardrail( @@ -771,7 +779,7 @@ def test_error_type_categorization_input_guardrail( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert ( call_kwargs["properties"]["$ai_error_type"] == "input_guardrail_triggered" ) @@ -789,7 +797,7 @@ def test_error_type_categorization_output_guardrail( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert ( call_kwargs["properties"]["$ai_error_type"] == "output_guardrail_triggered" ) @@ -805,7 +813,7 @@ def test_error_type_categorization_max_turns( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["properties"]["$ai_error_type"] == "max_turns_exceeded" def test_error_type_categorization_unknown(self, processor, mock_client, mock_span): @@ -817,7 +825,7 @@ def test_error_type_categorization_unknown(self, processor, mock_client, mock_sp processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["properties"]["$ai_error_type"] == "unknown" def test_response_span_with_output_and_total_tokens( @@ -843,7 +851,7 @@ def test_response_span_with_output_and_total_tokens( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["event"] == "$ai_generation" assert call_kwargs["properties"]["$ai_total_tokens"] == 35 @@ -872,7 +880,7 @@ def test_response_span_includes_total_cost( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["properties"]["$ai_total_cost_usd"] == total_cost_usd def test_speech_span_with_pass_through_properties( @@ -892,7 +900,7 @@ def test_speech_span_with_pass_through_properties( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["event"] == "$ai_span" assert call_kwargs["properties"]["$ai_span_type"] == "speech" @@ -925,7 +933,7 @@ def test_transcription_span_with_pass_through_properties( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["event"] == "$ai_span" assert call_kwargs["properties"]["$ai_span_type"] == "transcription" @@ -956,7 +964,7 @@ def test_transcription_span_audio_input_redacted( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["properties"]["$ai_input"] == "[base64 audio redacted]" def test_transcription_span_audio_input_passthrough( @@ -991,7 +999,7 @@ def test_latency_calculation(self, processor, mock_client, mock_span): mock_time.return_value = 1001.5 # 1.5 seconds later processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["properties"]["$ai_latency"] == pytest.approx(1.5, rel=0.01) def test_groups_included_in_events(self, mock_client, mock_trace, mock_span): @@ -1005,7 +1013,7 @@ def test_groups_included_in_events(self, mock_client, mock_trace, mock_span): processor.on_trace_start(mock_trace) processor.on_trace_end(mock_trace) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["groups"] == {"company": "acme", "team": "engineering"} def test_additional_properties_included(self, mock_client, mock_trace): @@ -1019,7 +1027,7 @@ def test_additional_properties_included(self, mock_client, mock_trace): processor.on_trace_start(mock_trace) processor.on_trace_end(mock_trace) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["properties"]["environment"] == "production" assert call_kwargs["properties"]["version"] == "1.0" @@ -1046,7 +1054,7 @@ def test_generation_span_with_no_usage(self, processor, mock_client, mock_span): processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert "$ai_input_tokens" not in call_kwargs["properties"] assert "$ai_output_tokens" not in call_kwargs["properties"] assert "$ai_total_tokens" not in call_kwargs["properties"] @@ -1064,7 +1072,7 @@ def test_generation_span_with_partial_usage( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["properties"]["$ai_input_tokens"] == 42 # The output side was never reported, so it is omitted rather than 0; # the total is the sum of the reported sides. @@ -1085,7 +1093,7 @@ def test_error_type_categorization_by_type_field_only( processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["properties"]["$ai_error_type"] == "model_behavior_error" def test_distinct_id_resolved_from_trace_for_spans( @@ -1103,7 +1111,7 @@ def resolver(trace): # Start trace - this resolves and stores distinct_id processor.on_trace_start(mock_trace) - mock_client.capture.reset_mock() + mock_client.capture_ai.reset_mock() # End a span - should use the stored distinct_id from trace span_data = GenerationSpanData(model="gpt-4o") @@ -1112,7 +1120,7 @@ def resolver(trace): processor.on_span_start(mock_span) processor.on_span_end(mock_span) - call_kwargs = mock_client.capture.call_args[1] + call_kwargs = mock_client.capture_ai.call_args[1] assert call_kwargs["distinct_id"] == "user-Test Workflow" def test_eviction_of_stale_entries(self, mock_client): @@ -1191,6 +1199,35 @@ def test_instrument_with_groups_and_properties(self, mock_client): assert processor._groups == {"company": "acme"} assert processor._properties == {"env": "test"} + @pytest.mark.parametrize( + "case", + POSTHOG_OPTIONS_CASES, + ids=[case[0] for case in POSTHOG_OPTIONS_CASES], + ) + def test_instrument_options_reach_trace_and_span_events( + self, mock_client, mock_trace, mock_span, caplog, case + ): + _, distinct_id, options, expected, warns = case + + with caplog.at_level(logging.WARNING, logger="posthog"): + with patch("agents.tracing.add_trace_processor"): + processor = instrument( + client=mock_client, distinct_id=distinct_id, options=options + ) + processor.on_trace_start(mock_trace) + mock_span.span_data = GenerationSpanData(model="gpt-4o") + processor.on_span_start(mock_span) + processor.on_span_end(mock_span) + processor.on_trace_end(mock_trace) + + calls = mock_client.capture_ai.call_args_list + assert [call.kwargs["event"] for call in calls] == [ + "$ai_generation", + "$ai_trace", + ] + for call in calls: + assert_captured_options(call.kwargs, expected, warns, caplog) + class TestCapturePolicy: def test_processor_groups_are_forwarded(self, mock_client): @@ -1201,91 +1238,13 @@ def test_processor_groups_are_forwarded(self, mock_client): processor._capture_event("$ai_trace", {}) - assert mock_client.capture.call_args.kwargs["groups"] == {"company": "acme"} + assert mock_client.capture_ai.call_args.kwargs["groups"] == {"company": "acme"} def test_capture_errors_are_logged_and_suppressed(self, mock_client, caplog): - mock_client.capture.side_effect = RuntimeError("capture failed") + mock_client.capture_ai.side_effect = RuntimeError("capture failed") processor = PostHogTracingProcessor(client=mock_client) with caplog.at_level(logging.DEBUG, logger="posthog"): processor._capture_event("$ai_trace", {}) assert "Failed to capture PostHog event: capture failed" in caplog.text - - -def test_ai_lane_client_routes_through_capture_ai(mock_client, mock_trace): - mock_client.enable_full_ai_capture = True - processor = PostHogTracingProcessor(client=mock_client, distinct_id="test-user") - processor.on_trace_start(mock_trace) - processor.on_trace_end(mock_trace) - - mock_client.capture.assert_not_called() - mock_client.capture_ai.assert_called_once() - assert mock_client.capture_ai.call_args[1]["event"] == "$ai_trace" - - -@pytest.mark.parametrize("full_capture", [False, True]) -@pytest.mark.parametrize("privacy", [False, True]) -def test_transcription_privacy_wins_over_full_capture_without_mutating_config( - mock_client, mock_span, full_capture, privacy -): - mock_client.enable_full_ai_capture = full_capture - processor = PostHogTracingProcessor( - client=mock_client, distinct_id="audio-user", privacy_mode=privacy - ) - config = { - "prompt": "private prompt", - "instructions": "private instructions", - "language": "en", - } - data = TranscriptionSpanData( - input="AAAA", - input_format="pcm", - output="private transcript", - model_config=config, - ) - mock_span.span_data = data - processor.on_span_end(mock_span) - - capture = mock_client.capture_ai if full_capture else mock_client.capture - capture.assert_called_once() - props = capture.call_args.kwargs["properties"] - assert capture.call_args.kwargs["distinct_id"] == "audio-user" - assert props["$ai_input"] == ( - None if privacy else "AAAA" if full_capture else "[base64 audio redacted]" - ) - assert props["$ai_output_state"] == (None if privacy else "private transcript") - assert props["model_config"] == { - "prompt": None if privacy else "private prompt", - "instructions": None if privacy else "private instructions", - "language": "en", - } - assert ( - data.model_config - == config - == { - "prompt": "private prompt", - "instructions": "private instructions", - "language": "en", - } - ) - - -def test_span_error_category_keeps_precedence_and_privacy_summary( - mock_client, mock_span -): - processor = PostHogTracingProcessor(client=mock_client, privacy_mode=True) - mock_client.enable_full_ai_capture = False - mock_span.span_data = GenerationSpanData(model="gpt-4o", usage={"input_tokens": 0}) - mock_span.error = { - "type": "UserError", - "message": "private ModelBehaviorError and MaxTurnsExceeded", - } - processor.on_span_end(mock_span) - - props = mock_client.capture.call_args.kwargs["properties"] - assert props["$ai_error_type"] == "model_behavior_error" - assert props["$ai_error"] == "UserError" - assert props["$ai_input_tokens"] == props["$ai_total_tokens"] == 0 - assert "$ai_output_tokens" not in props - assert props["$process_person_profile"] is False diff --git a/posthog/test/ai/test_capture_contract.py b/posthog/test/ai/test_capture_contract.py index 5b4951c76..987e39bec 100644 --- a/posthog/test/ai/test_capture_contract.py +++ b/posthog/test/ai/test_capture_contract.py @@ -246,7 +246,7 @@ class FakePH: def __init__(self): self.events = [] - def capture(self, *args, **kwargs): + def capture_ai(self, *args, **kwargs): self.events.append(kwargs) def flush(self): diff --git a/posthog/test/ai/test_capture_pipeline.py b/posthog/test/ai/test_capture_pipeline.py index 916ad8416..cacbac8d3 100644 --- a/posthog/test/ai/test_capture_pipeline.py +++ b/posthog/test/ai/test_capture_pipeline.py @@ -12,7 +12,7 @@ class FakePH: def __init__(self): self.events = [] - def capture(self, *args, **kwargs): + def capture_ai(self, *args, **kwargs): self.events.append(kwargs) def flush(self): diff --git a/posthog/test/ai/test_http_status.py b/posthog/test/ai/test_http_status.py index 8f464079a..85d744481 100644 --- a/posthog/test/ai/test_http_status.py +++ b/posthog/test/ai/test_http_status.py @@ -71,7 +71,7 @@ def boom(**kwargs): contents="hi", ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_is_error"] is True assert props["$ai_http_status"] == code @@ -99,7 +99,7 @@ async def boom(**kwargs): contents="hi", ) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] assert props["$ai_http_status"] == 429 @@ -121,7 +121,7 @@ def boom(**kwargs): model="m", ) - assert mock_client.capture.call_args[1]["properties"]["$ai_http_status"] == 503 + assert mock_client.capture_ai.call_args[1]["properties"]["$ai_http_status"] == 503 def _anthropic_stream_error_event(error_type): diff --git a/posthog/test/ai/test_stream_midstream_error.py b/posthog/test/ai/test_stream_midstream_error.py index 620b5990c..676051144 100644 --- a/posthog/test/ai/test_stream_midstream_error.py +++ b/posthog/test/ai/test_stream_midstream_error.py @@ -16,8 +16,8 @@ def mock_client(): def _props(mock_client): - assert mock_client.capture.call_count == 1 - return mock_client.capture.call_args[1]["properties"] + assert mock_client.capture_ai.call_count == 1 + return mock_client.capture_ai.call_args[1]["properties"] class _StatusError(RuntimeError): @@ -273,6 +273,19 @@ class _ConnectError(RuntimeError): status_code = 401 +# A caller's options must reach the error event too. No distinct id, so the +# event is personless and process_person_profile: False joins the caller's. +_CALLER = {"posthog_options": {"cookieless_mode": True}} +_SENT_OPTIONS = {"cookieless_mode": True, "process_person_profile": False} + + +def _assert_connect_error_event(mock_client): + props = _props(mock_client) + assert props["$ai_is_error"] is True + assert props["$ai_http_status"] == 401 + assert mock_client.capture_ai.call_args[1]["options"] == _SENT_OPTIONS + + def test_openai_chat_stream_connect_error(mock_client): from posthog.ai.openai import OpenAI @@ -284,11 +297,10 @@ def test_openai_chat_stream_connect_error(mock_client): model="gpt-4", messages=[{"role": "user", "content": "hi"}], stream=True, + **_CALLER, ) - props = _props(mock_client) - assert props["$ai_is_error"] is True - assert props["$ai_http_status"] == 401 + _assert_connect_error_event(mock_client) @pytest.mark.asyncio @@ -307,11 +319,10 @@ async def create(**kwargs): model="gpt-4", messages=[{"role": "user", "content": "hi"}], stream=True, + **_CALLER, ) - props = _props(mock_client) - assert props["$ai_is_error"] is True - assert props["$ai_http_status"] == 401 + _assert_connect_error_event(mock_client) def test_openai_responses_stream_connect_error(mock_client): @@ -321,11 +332,9 @@ def test_openai_responses_stream_connect_error(mock_client): create.side_effect = _ConnectError("bad key") client = OpenAI(api_key="k", posthog_client=mock_client) with pytest.raises(_ConnectError): - client.responses.create(model="gpt-4", input="hi", stream=True) + client.responses.create(model="gpt-4", input="hi", stream=True, **_CALLER) - props = _props(mock_client) - assert props["$ai_is_error"] is True - assert props["$ai_http_status"] == 401 + _assert_connect_error_event(mock_client) @pytest.mark.asyncio @@ -338,11 +347,11 @@ async def create(**kwargs): with patch("openai.resources.responses.AsyncResponses.create", side_effect=create): client = AsyncOpenAI(api_key="k", posthog_client=mock_client) with pytest.raises(_ConnectError): - await client.responses.create(model="gpt-4", input="hi", stream=True) + await client.responses.create( + model="gpt-4", input="hi", stream=True, **_CALLER + ) - props = _props(mock_client) - assert props["$ai_is_error"] is True - assert props["$ai_http_status"] == 401 + _assert_connect_error_event(mock_client) def test_anthropic_stream_connect_error(mock_client): @@ -357,11 +366,10 @@ def test_anthropic_stream_connect_error(mock_client): messages=[{"role": "user", "content": "hi"}], max_tokens=5, stream=True, + **_CALLER, ) - props = _props(mock_client) - assert props["$ai_is_error"] is True - assert props["$ai_http_status"] == 401 + _assert_connect_error_event(mock_client) @pytest.mark.asyncio @@ -379,11 +387,10 @@ async def create(**kwargs): messages=[{"role": "user", "content": "hi"}], max_tokens=5, stream=True, + **_CALLER, ) - props = _props(mock_client) - assert props["$ai_is_error"] is True - assert props["$ai_http_status"] == 401 + _assert_connect_error_event(mock_client) def test_gemini_stream_connect_error(mock_client): @@ -399,12 +406,10 @@ def test_gemini_stream_connect_error(mock_client): client = Client(api_key="k", posthog_client=mock_client) with pytest.raises(_ConnectError): client.models.generate_content_stream( - model="gemini-2.0-flash", contents=["hi"] + model="gemini-2.0-flash", contents=["hi"], **_CALLER ) - props = _props(mock_client) - assert props["$ai_is_error"] is True - assert props["$ai_http_status"] == 401 + _assert_connect_error_event(mock_client) @pytest.mark.asyncio @@ -423,12 +428,10 @@ async def test_gemini_stream_connect_error_async(mock_client): client = AsyncClient(api_key="k", posthog_client=mock_client) with pytest.raises(_ConnectError): await client.models.generate_content_stream( - model="gemini-2.0-flash", contents=["hi"] + model="gemini-2.0-flash", contents=["hi"], **_CALLER ) - props = _props(mock_client) - assert props["$ai_is_error"] is True - assert props["$ai_http_status"] == 401 + _assert_connect_error_event(mock_client) @pytest.mark.parametrize( diff --git a/posthog/test/ai/test_token_reporting.py b/posthog/test/ai/test_token_reporting.py index 790a3a6db..e06c2f075 100644 --- a/posthog/test/ai/test_token_reporting.py +++ b/posthog/test/ai/test_token_reporting.py @@ -52,7 +52,7 @@ def test_token_counts_trace_back_to_a_provider_report( ): capture_streaming_event(mock_client, _event_data(usage_stats)) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] for key in ("$ai_input_tokens", "$ai_output_tokens"): if key in expected: assert props[key] == expected[key] @@ -85,7 +85,7 @@ def test_aux_token_fields_trace_back_to_a_provider_report( ): capture_streaming_event(mock_client, _event_data(usage_stats, provider=provider)) - props = mock_client.capture.call_args[1]["properties"] + props = mock_client.capture_ai.call_args[1]["properties"] for key in ( "$ai_cache_read_input_tokens", "$ai_cache_creation_input_tokens", diff --git a/posthog/test/ai/utils.py b/posthog/test/ai/utils.py index 9f27c1f38..7aecc547f 100644 --- a/posthog/test/ai/utils.py +++ b/posthog/test/ai/utils.py @@ -88,3 +88,55 @@ async def __anext__(self): async def close(self): self.closed = True + + +# Each case: name, distinct ID passed to the wrapper, posthog_options passed +# (None means the argument is left out), expected ``options`` kwarg of +# ``capture_ai`` (None means no ``options`` kwarg), and whether a non-dict +# warning is logged. +POSTHOG_OPTIONS_CASES = [ + ( + "identified_keeps_user_values", + "user-1", + {"cookieless_mode": True, "process_person_profile": True}, + {"cookieless_mode": True, "process_person_profile": True}, + False, + ), + ( + "personless_false_beats_user_true", + None, + {"cookieless_mode": True, "process_person_profile": True}, + {"cookieless_mode": True, "process_person_profile": False}, + False, + ), + ("unset_sends_no_options", "user-1", None, None, False), + ("non_dict_is_ignored", "user-1", "cookieless_mode", None, True), + ( + "non_dict_is_ignored_personless", + None, + ["cookieless_mode"], + {"process_person_profile": False}, + True, + ), +] + +NON_DICT_OPTIONS_WARNING = "posthog_options must be a dict" + + +def posthog_call_kwargs(distinct_id, posthog_options): + """The PostHog arguments of one wrapper call, leaving out unset ones.""" + kwargs = {} + if distinct_id is not None: + kwargs["posthog_distinct_id"] = distinct_id + if posthog_options is not None: + kwargs["posthog_options"] = posthog_options + return kwargs + + +def assert_captured_options(capture_kwargs, expected, warns, caplog): + """Check the ``options`` kwarg of one ``capture_ai`` call and the warning log.""" + if expected is None: + assert "options" not in capture_kwargs + else: + assert capture_kwargs["options"] == expected + assert (NON_DICT_OPTIONS_WARNING in caplog.text) is warns diff --git a/posthog/test/capture_helpers.py b/posthog/test/capture_helpers.py new file mode 100644 index 000000000..d32f4741f --- /dev/null +++ b/posthog/test/capture_helpers.py @@ -0,0 +1,72 @@ +"""Intercept capture uploads at the batch submitter for client-level tests. + +Patching the submitter (not the HTTP layer) lets tests assert on the event +dicts the SDK built, before the wire encoding in ``capture_event``. Wire shape is +covered by ``test_capture_event``. +""" + +import json +from unittest import mock + +from requests import Response + +_SUBMITTER = "_send_v1_batch" + + +def offline_v1_post(url: str, data=None, **kwargs) -> Response: + """Stand-in for ``requests.Session.post`` that accepts every v1 event. + + For subprocess tests with no server. Prints the uncompressed request body, + because the SDK never logs payloads, and answers ``ok`` for each event. + """ + print(f"capture request body: {data}", flush=True) # noqa: T201 + events = json.loads(data)["batch"] + response = Response() + response.status_code = 200 + response._content = json.dumps( + {"results": {event["uuid"]: {"result": "ok"} for event in events}} + ).encode() + return response + + +def patch_capture_send(site: str = "client", **kwargs) -> "mock._patch": + """Patch the submitter where ``posthog.`` imported it. + + ``site="client"`` sees ``sync_mode`` uploads; ``site="consumer"`` sees + background consumer uploads. + """ + return mock.patch(f"posthog.{site}.{_SUBMITTER}", **kwargs) + + +def record_sync_capture_sends(test_case) -> list[dict]: + """Record every event a ``sync_mode`` client uploads until ``test_case`` ends.""" + events: list[dict] = [] + + def record(*args, **kwargs): + events.extend(args[2] if len(args) > 2 else kwargs["batch"]) + return mock.DEFAULT + + patcher = patch_capture_send("client", side_effect=record) + patcher.start() + test_case.addCleanup(patcher.stop) + return events + + +def patch_async_capture_send(**kwargs) -> "mock._patch": + """Patch the submitter the ``AsyncPosthog`` consumer awaits.""" + return mock.patch("posthog._async_consumer.async_send_v1_batch", **kwargs) + + +def sent_batch(send_mock: mock.Mock, call_index: int = -1) -> list[dict]: + """Return the event batch from one recorded upload (default: the last).""" + call = send_mock.call_args_list[call_index] + return call.args[2] if len(call.args) > 2 else call.kwargs["batch"] + + +def sent_events(send_mock: mock.Mock) -> list[dict]: + """Return every event uploaded through ``send_mock``, in send order.""" + return [ + event + for index in range(len(send_mock.call_args_list)) + for event in sent_batch(send_mock, index) + ] diff --git a/posthog/test/integrations/test_celery_integration.py b/posthog/test/integrations/test_celery_integration.py index 9a4a7ad15..d025a7d6f 100644 --- a/posthog/test/integrations/test_celery_integration.py +++ b/posthog/test/integrations/test_celery_integration.py @@ -1,3 +1,4 @@ +import json import unittest from types import ModuleType from types import SimpleNamespace @@ -6,8 +7,11 @@ from parameterized import parameterized from posthog import contexts +from posthog.capture_event import _to_v1_event +from posthog.client import Client from posthog.integrations.celery import ( CONTEXT_DISTINCT_ID_HEADER, + CONTEXT_OPTIONS_HEADER, CONTEXT_SESSION_ID_HEADER, CONTEXT_TAGS_HEADER, PosthogCeleryIntegration, @@ -208,19 +212,39 @@ def test_before_task_publish_propagates_context_headers(self): contexts.identify_context("distinct-123") contexts.set_context_session("session-456") contexts.tag("request_id", "abc") + contexts.set_context_option("cookieless_mode", True) integration._on_before_task_publish(sender="test.task", headers=headers) self.assertEqual(headers[CONTEXT_DISTINCT_ID_HEADER], "distinct-123") self.assertEqual(headers[CONTEXT_SESSION_ID_HEADER], "session-456") - self.assertIn(CONTEXT_TAGS_HEADER, headers) + self.assertEqual( + json.loads(headers[CONTEXT_TAGS_HEADER]), {"request_id": "abc"} + ) + self.assertEqual( + json.loads(headers[CONTEXT_OPTIONS_HEADER]), {"cookieless_mode": True} + ) # celery#4875: headers must also be nested inside headers["headers"] # so they survive to task.request.headers on the worker inner = headers["headers"] self.assertEqual(inner[CONTEXT_DISTINCT_ID_HEADER], "distinct-123") self.assertEqual(inner[CONTEXT_SESSION_ID_HEADER], "session-456") - self.assertIn(CONTEXT_TAGS_HEADER, inner) + self.assertEqual(json.loads(inner[CONTEXT_TAGS_HEADER]), {"request_id": "abc"}) + self.assertEqual( + json.loads(inner[CONTEXT_OPTIONS_HEADER]), {"cookieless_mode": True} + ) + + def test_before_task_publish_skips_options_header_without_context_options(self): + integration = PosthogCeleryIntegration() + headers = {} + + with contexts.new_context(fresh=True): + contexts.tag("request_id", "abc") + integration._on_before_task_publish(sender="test.task", headers=headers) + + self.assertNotIn(CONTEXT_OPTIONS_HEADER, headers) + self.assertNotIn(CONTEXT_OPTIONS_HEADER, headers["headers"]) def test_before_task_publish_preserves_existing_nested_headers(self): integration = PosthogCeleryIntegration() @@ -242,6 +266,7 @@ def test_before_task_publish_nested_headers_round_trips_to_worker(self): contexts.identify_context("user-rt") contexts.set_context_session("sess-rt") contexts.tag("env", "test") + contexts.set_context_option("process_person_profile", False) integration._on_before_task_publish(sender="test.task", headers=headers) # Simulate Celery worker: task.request.headers is the nested dict @@ -258,6 +283,9 @@ def test_before_task_publish_nested_headers_round_trips_to_worker(self): self.assertEqual(contexts.get_context_distinct_id(), "user-rt") self.assertEqual(contexts.get_context_session_id(), "sess-rt") self.assertEqual(contexts.get_tags().get("env"), "test") + self.assertEqual( + contexts.get_context_options(), {"process_person_profile": False} + ) # close out the task lifecycle so the test doesn't leave context hanging around integration._on_task_success(sender=task) @@ -317,6 +345,7 @@ def test_before_task_publish_respects_propagate_context_flag(self): contexts.identify_context("distinct-123") contexts.set_context_session("session-456") contexts.tag("request_id", "abc") + contexts.set_context_option("process_person_profile", False) integration._on_before_task_publish(sender="test.task", headers=headers) @@ -758,10 +787,194 @@ def test_prerun_exits_context_on_failure_after_entry(self): ctx_after = contexts._get_current_context() self.assertIs(ctx_after, ctx_before) - def test_extract_propagated_tags_invalid_json_returns_empty_dict(self): + @parameterized.expand( + [ + ("tags", CONTEXT_TAGS_HEADER, "_extract_propagated_tags"), + ("options", CONTEXT_OPTIONS_HEADER, "_extract_propagated_options"), + ] + ) + def test_extract_propagated_header_invalid_json_returns_empty_dict( + self, _name, header, extractor + ): integration = PosthogCeleryIntegration() - request = SimpleNamespace(headers={CONTEXT_TAGS_HEADER: "{bad json"}) + request = SimpleNamespace(headers={header: "{bad json"}) - tags = integration._extract_propagated_tags(request) + self.assertEqual(getattr(integration, extractor)(request), {}) - self.assertEqual(tags, {}) + +def _set_producer_context(distinct_id=None, tags=None, options=None): + if distinct_id: + contexts.identify_context(distinct_id) + for key, value in (tags or {}).items(): + contexts.tag(key, value) + for key, value in (options or {}).items(): + contexts.set_context_option(key, value) + + +class TestCeleryContextOptionsOnTheWire(unittest.TestCase): + """Checks the options worker events send, through a real client.""" + + def _client(self, **kwargs): + sent = [] + client = Client( + "phc_test", + send=False, + before_send=lambda msg: sent.append(msg) or msg, + **kwargs, + ) + return client, sent + + def _worker_task(self, headers): + request = SimpleNamespace( + headers=headers, delivery_info={}, hostname="worker-1", retries=0 + ) + return SimpleNamespace(name="app.tasks.example", request=request) + + def _run_worker(self, integration, client, headers, in_task=None): + task = self._worker_task(headers) + integration._on_task_prerun(sender=task, task_id="task-1") + if in_task: + in_task() + client.capture("in task") + integration._on_task_success(sender=task) + + def _publish_and_run( + self, producer, super_options=None, in_task=None, propagate_context=True + ): + kwargs = {"super_options": super_options} if super_options else {} + client, sent = self._client(**kwargs) + integration = PosthogCeleryIntegration( + client=client, propagate_context=propagate_context + ) + headers = {} + with contexts.new_context(fresh=True, client=client): + _set_producer_context(**producer) + integration._on_before_task_publish(sender="t", headers=headers) + self._run_worker(integration, client, headers.get("headers", {}), in_task) + return { + event["event"]: event["options"] + for event in (_to_v1_event(msg) for msg in sent) + } + + @parameterized.expand( + [ + ( + "all_four_options", + { + "distinct_id": "user-1", + "options": { + "process_person_profile": False, + "cookieless_mode": True, + "disable_skew_correction": True, + "product_tour_id": "tour-1", + }, + }, + None, + { + "process_person_profile": False, + "cookieless_mode": True, + "disable_skew_correction": True, + "product_tour_id": "tour-1", + }, + ), + ( + "option_beats_legacy_tag_on_same_key", + { + "distinct_id": "user-1", + "tags": {"$process_person_profile": True}, + "options": {"process_person_profile": False}, + }, + None, + {"process_person_profile": False}, + ), + ( + "legacy_tag_only", + {"distinct_id": "user-1", "tags": {"$process_person_profile": False}}, + None, + {"process_person_profile": False}, + ), + ( + "context_option_beats_worker_super_options", + {"distinct_id": "user-1", "options": {"cookieless_mode": False}}, + {"cookieless_mode": True}, + {"cookieless_mode": False}, + ), + ( + "personless_process_person_profile_true", + {"options": {"process_person_profile": True}}, + None, + {"process_person_profile": True}, + ), + ] + ) + def test_worker_events_send_propagated_options( + self, _name, producer, super_options, expected + ): + options_by_event = self._publish_and_run(producer, super_options) + + self.assertEqual( + options_by_event, + { + "celery task started": expected, + "in task": expected, + "celery task success": expected, + }, + ) + + def test_option_set_inside_task_overrides_propagated_option(self): + options_by_event = self._publish_and_run( + {"distinct_id": "user-1", "options": {"process_person_profile": False}}, + in_task=lambda: contexts.set_context_option("process_person_profile", True), + ) + + self.assertEqual( + options_by_event, + { + "celery task started": {"process_person_profile": False}, + "in task": {"process_person_profile": True}, + "celery task success": {"process_person_profile": True}, + }, + ) + + @parameterized.expand( + [ + ("missing", None, {}), + ("bad_json", "{bad json", {}), + ("not_an_object", '["cookieless_mode"]', {}), + ("bytes", b'{"cookieless_mode": true}', {"cookieless_mode": True}), + ] + ) + def test_worker_handles_options_header(self, _name, raw, expected): + client, sent = self._client() + integration = PosthogCeleryIntegration(client=client) + headers = {CONTEXT_DISTINCT_ID_HEADER: "user-1"} + if raw is not None: + headers[CONTEXT_OPTIONS_HEADER] = raw + + self._run_worker(integration, client, headers) + + self.assertEqual( + [(msg["event"], _to_v1_event(msg)["options"]) for msg in sent], + [ + ("celery task started", expected), + ("in task", expected), + ("celery task success", expected), + ], + ) + + def test_propagate_context_false_sends_no_options(self): + options_by_event = self._publish_and_run( + {"distinct_id": "user-1", "options": {"cookieless_mode": True}}, + propagate_context=False, + ) + + # The distinct ID is not propagated either, so worker events are personless. + personless = {"process_person_profile": False} + self.assertEqual( + options_by_event, + { + "celery task started": personless, + "in task": personless, + "celery task success": personless, + }, + ) diff --git a/posthog/test/integrations/test_middleware_api.py b/posthog/test/integrations/test_middleware_api.py index af68247a7..789e552dc 100644 --- a/posthog/test/integrations/test_middleware_api.py +++ b/posthog/test/integrations/test_middleware_api.py @@ -154,8 +154,8 @@ async def async_view(request): ), patch.object( client, - "_enqueue", - side_effect=lambda message, *args, **kwargs: captured.append(message), + "before_send", + new=lambda message: captured.append(message), ), ): middleware = PosthogContextMiddleware(async_view if asynchronous else view) diff --git a/posthog/test/integrations/test_tracing_headers.py b/posthog/test/integrations/test_tracing_headers.py index 39edf7c21..ffc8f8068 100644 --- a/posthog/test/integrations/test_tracing_headers.py +++ b/posthog/test/integrations/test_tracing_headers.py @@ -202,9 +202,7 @@ def capture(): event = enqueue.call_args.args[0] assert UUID(event["distinct_id"]) assert event["properties"]["$session_id"] == "header-session" - assert event["properties"]["$process_person_profile"] is ( - process_person_profile if process_person_profile is not None else False - ) + assert enqueue.call_args.kwargs["personless"] is True @pytest.mark.asyncio diff --git a/posthog/test/logging_helpers.py b/posthog/test/logging_helpers.py index ae1ca6fdc..629963764 100644 --- a/posthog/test/logging_helpers.py +++ b/posthog/test/logging_helpers.py @@ -1,7 +1,7 @@ import io import logging from contextlib import contextmanager -from typing import Iterator +from typing import Iterator, Sequence from posthog._logging import _POSTHOG_LOGGER_NAME @@ -25,3 +25,18 @@ def capture_message_only_logs(level: int = logging.DEBUG) -> Iterator[io.StringI handler.close() logger.setLevel(previous_level) logger.propagate = previous_propagate + + +def assert_before_send_failure_logged( + records: Sequence[logging.LogRecord], event_name: str, error_type: str +) -> None: + errors = [r for r in records if r.levelno >= logging.ERROR] + assert [r.getMessage() for r in errors] == [ + f"[PostHog] Error in before_send callback for event {event_name} " + f"({error_type}), dropping the event" + ] + assert errors[0].exc_info is None + tracebacks = [r for r in records if r.exc_info] + assert [(r.levelno, r.exc_info[0].__name__) for r in tracebacks] == [ + (logging.DEBUG, error_type) + ] diff --git a/posthog/test/mcp/_helpers.py b/posthog/test/mcp/_helpers.py index 4cfdbc5ff..adf5c537f 100644 --- a/posthog/test/mcp/_helpers.py +++ b/posthog/test/mcp/_helpers.py @@ -29,7 +29,12 @@ def capture( **kwargs, ): self.events.append( - {"event": event, "distinct_id": distinct_id, "properties": properties or {}} + { + "event": event, + "distinct_id": distinct_id, + "properties": properties or {}, + "options": kwargs.get("options") or {}, + } ) return None diff --git a/posthog/test/mcp/test_fastmcp.py b/posthog/test/mcp/test_fastmcp.py index 5be832d69..632850d60 100644 --- a/posthog/test/mcp/test_fastmcp.py +++ b/posthog/test/mcp/test_fastmcp.py @@ -255,7 +255,7 @@ async def test_identify_sets_distinct_id_and_groups(): calls = _events(client, "$mcp_tool_call") assert calls[0]["distinct_id"] == "user_42" assert calls[0]["properties"]["$groups"] == {"organization": "org_7"} - assert "$process_person_profile" not in calls[0]["properties"] + assert calls[0]["options"] == {} assert not _events(client, "$identify") diff --git a/posthog/test/mcp/test_features_m4.py b/posthog/test/mcp/test_features_m4.py index 561162cad..ff41a375f 100644 --- a/posthog/test/mcp/test_features_m4.py +++ b/posthog/test/mcp/test_features_m4.py @@ -296,13 +296,16 @@ async def _ct(name, arguments): ) -async def test_event_properties_applied_to_all_event_types(): +async def test_event_properties_and_options_applied_to_all_event_types(): server = make_lowlevel() client = FakeClient() instrument( server, client, - MCPAnalyticsOptions(event_properties=lambda request, extra: {"tenant": "acme"}), + MCPAnalyticsOptions( + event_properties=lambda request, extra: {"tenant": "acme"}, + event_options=lambda request, extra: {"cookieless_mode": True}, + ), ) await server.request_handlers[mcp_types.ListToolsRequest]( @@ -320,6 +323,10 @@ async def test_event_properties_applied_to_all_event_types(): assert evs[0]["properties"].get("tenant") == "acme", ( f"{name} missing event_properties" ) + assert evs[0]["options"] == { + "cookieless_mode": True, + "process_person_profile": False, + }, f"{name} missing event_options" # --- PostHogMCP -------------------------------------------------------------- diff --git a/posthog/test/mcp/test_lib_label.py b/posthog/test/mcp/test_lib_label.py new file mode 100644 index 000000000..ea3155ea3 --- /dev/null +++ b/posthog/test/mcp/test_lib_label.py @@ -0,0 +1,226 @@ +"""``posthog-python-mcp`` labels the MCP pipeline's events, and only those.""" + +from datetime import datetime, timezone +from unittest import mock + +import pytest + +from posthog.async_client import AsyncClient +from posthog.capture_event import _to_v1_event +from posthog.client import Client +from posthog.contexts import new_context, tag +from posthog.mcp import instrument +from posthog.mcp._event_types import MCPAnalyticsEventType +from posthog.mcp._sink import McpCaptureOptions, McpEventSink +from posthog.mcp.posthog_mcp import PostHogMCP +from posthog.test.mcp._helpers import MCP_MAJOR, flush_background +from posthog.test.capture_helpers import ( + patch_async_capture_send, + patch_capture_send, + sent_batch, + sent_events, +) +from posthog.version import VERSION + +MCP_LIB = ("posthog-python-mcp", VERSION) +SDK_LIB = ("posthog-python", VERSION) + + +def _tool_call(**overrides): + event = { + "event_type": MCPAnalyticsEventType.MCP_TOOLS_CALL, + "session_id": "ses_abc", + "resource_name": "search", + "timestamp": datetime.now(timezone.utc), + } + event.update(overrides) + return event + + +def _failed_tool_call(): + return _tool_call(is_error=True, error={"message": "boom", "type": "ValueError"}) + + +def _lib(properties): + return (properties.get("$lib"), properties.get("$lib_version")) + + +def _sync_wire(send): + return {e["event"]: e["properties"] for e in map(_to_v1_event, sent_events(send))} + + +async def test_sync_client_labels_mcp_events_and_not_app_events(): + with patch_capture_send("client") as send: + client = Client("phc_test", sync_mode=True) + await McpEventSink(client).capture(_failed_tool_call(), McpCaptureOptions()) + client.capture("app event", distinct_id="user-1") + + wire = _sync_wire(send) + assert _lib(wire["$mcp_tool_call"]) == MCP_LIB + assert _lib(wire["$exception"]) == MCP_LIB + assert _lib(wire["app event"]) == SDK_LIB + assert {c.kwargs["sdk_info"] for c in send.call_args_list} == { + f"posthog-python/{VERSION}" + } + + +async def test_async_client_labels_mcp_events_and_not_app_events(): + with patch_async_capture_send(new=mock.AsyncMock()) as send: + client = AsyncClient("phc_test") + await McpEventSink(client).capture(_failed_tool_call(), McpCaptureOptions()) + client.capture("app event", distinct_id="user-1") + await client.shutdown() + + wire = { + e["event"]: e["properties"] + for index in range(len(send.await_args_list)) + for e in sent_batch(send, index) + } + assert _lib(wire["$mcp_tool_call"]) == MCP_LIB + assert _lib(wire["$exception"]) == MCP_LIB + assert _lib(wire["app event"]) == SDK_LIB + + +@pytest.mark.parametrize("client_kind", ["sync", "async"]) +async def test_instrumented_server_labels_its_tool_calls(client_kind): + if MCP_MAJOR >= 2: + from mcp.server.mcpserver import MCPServer as Server + else: + from mcp.server.fastmcp import FastMCP as Server + + server = Server(f"lib-label-{client_kind}") + + @server.tool() + def echo(msg: str) -> str: + return msg + + if client_kind == "sync": + with patch_capture_send("client") as send: + client = Client("phc_test", sync_mode=True) + instrument(server, client) + await server._tool_manager.call_tool("echo", {"msg": "hi"}) + await flush_background() + client.capture("app event", distinct_id="user-1") + wire = _sync_wire(send) + else: + with patch_async_capture_send(new=mock.AsyncMock()) as send: + client = AsyncClient("phc_test") + instrument(server, client) + await server._tool_manager.call_tool("echo", {"msg": "hi"}) + await flush_background() + client.capture("app event", distinct_id="user-1") + await client.shutdown() + wire = { + e["event"]: e["properties"] + for index in range(len(send.await_args_list)) + for e in sent_batch(send, index) + } + + assert _lib(wire["$mcp_tool_call"]) == MCP_LIB + assert _lib(wire["app event"]) == SDK_LIB + + +def test_posthog_mcp_labels_tool_calls_and_not_custom_events(): + with patch_capture_send("client") as send: + client = PostHogMCP("phc_test", sync_mode=True) + client.capture_tool_call("search", distinct_id="user-1", session_id="ses_abc") + client.flush() + client.capture("app event", distinct_id="user-1") + + wire = _sync_wire(send) + assert _lib(wire["$mcp_tool_call"]) == MCP_LIB + assert _lib(wire["app event"]) == SDK_LIB + + +def test_instrument_without_a_client_leaves_the_default_client_unlabeled(): + from mcp.server.lowlevel import Server + + with patch_capture_send("client") as send: + default_client = Client("phc_test", sync_mode=True) + with mock.patch("posthog.setup", return_value=default_client): + instrument(Server("probe-default-client")) + default_client.capture("app event", distinct_id="user-1") + + assert _lib(_sync_wire(send)["app event"]) == SDK_LIB + assert send.call_args.kwargs["sdk_info"] == f"posthog-python/{VERSION}" + + +@pytest.mark.parametrize( + "properties, expected", + [ + ({"$lib": "my-wrapper", "$lib_version": "2.0.0"}, ("my-wrapper", "2.0.0")), + ({"$lib": "my-wrapper"}, ("my-wrapper", None)), + ({"$lib_version": "9.9.9"}, MCP_LIB), + ({"$lib": ""}, MCP_LIB), + ({"$lib": None, "$lib_version": "9.9.9"}, MCP_LIB), + ({"$lib": 5}, MCP_LIB), + ({"$lib": "posthog-python-mcp"}, MCP_LIB), + ({"$lib": "posthog-python"}, SDK_LIB), + ], + ids=[ + "app_pair_wins", + "app_lib_keeps_no_version", + "lone_version_replaced", + "empty_lib_unset", + "null_lib_unset", + "number_lib_unset", + "label_gets_version", + "sdk_lib_gets_version", + ], +) +async def test_event_properties_follow_the_pair_rule(properties, expected): + with patch_capture_send("client") as send: + client = Client("phc_test", sync_mode=True) + await McpEventSink(client).capture( + _tool_call(properties=properties), McpCaptureOptions() + ) + + assert _lib(_sync_wire(send)["$mcp_tool_call"]) == expected + + +@pytest.mark.parametrize("layer", ["super_properties", "context_tag"]) +async def test_mcp_label_beats_lower_layers_but_not_on_app_events(layer): + wrapper = {"$lib": "my-wrapper", "$lib_version": "2.0.0"} + with patch_capture_send("client") as send: + client = Client( + "phc_test", + sync_mode=True, + super_properties=wrapper if layer == "super_properties" else None, + ) + with new_context(fresh=True): + if layer == "context_tag": + for key, value in wrapper.items(): + tag(key, value) + await McpEventSink(client).capture(_tool_call(), McpCaptureOptions()) + client.capture("app event", distinct_id="user-1") + + wire = _sync_wire(send) + assert _lib(wire["$mcp_tool_call"]) == MCP_LIB + assert _lib(wire["app event"]) == ("my-wrapper", "2.0.0") + + +def _relabel(event): + event["properties"]["$lib"] = "my-wrapper" + event["properties"]["$lib_version"] = "2.0.0" + return event + + +def _unlabel(event): + event["properties"].pop("$lib") + event["properties"].pop("$lib_version") + return event + + +@pytest.mark.parametrize( + "before_send, expected", + [(_relabel, ("my-wrapper", "2.0.0")), (_unlabel, SDK_LIB)], + ids=["mcp_before_send_relabels", "removal_falls_back_to_the_sdk_pair"], +) +async def test_mcp_before_send_sees_the_label(before_send, expected): + with patch_capture_send("client") as send: + client = Client("phc_test", sync_mode=True) + await McpEventSink(client).capture( + _tool_call(), McpCaptureOptions(before_send=before_send) + ) + + assert _lib(_sync_wire(send)["$mcp_tool_call"]) == expected diff --git a/posthog/test/mcp/test_no_crash.py b/posthog/test/mcp/test_no_crash.py index ffe0f4a3d..72713c841 100644 --- a/posthog/test/mcp/test_no_crash.py +++ b/posthog/test/mcp/test_no_crash.py @@ -61,7 +61,7 @@ def test_low_level_server_detected_on_installed_major(): assert compat.is_low_level_server(object()) is False -def test_instrument_relabels_the_host_client(): +def test_instrument_keeps_the_host_client_identity(): from mcp.server.lowlevel import Server captured = [] @@ -74,7 +74,7 @@ def before_send(event): instrument(Server("probe-lib-identity"), client) client.capture("after instrumentation") - assert captured[0]["properties"]["$lib"] == "posthog-python-mcp" + assert captured[0]["properties"]["$lib"] == "posthog-python" assert captured[0]["properties"]["$lib_version"] == VERSION diff --git a/posthog/test/mcp/test_pipeline.py b/posthog/test/mcp/test_pipeline.py index 1e8728920..59cb0c46f 100644 --- a/posthog/test/mcp/test_pipeline.py +++ b/posthog/test/mcp/test_pipeline.py @@ -1,8 +1,9 @@ """Unit tests for the MCP analytics core pipeline (Milestone 1, no server).""" +import copy import json -import re import random +import re from datetime import datetime, timezone import pytest @@ -23,8 +24,25 @@ sanitize_captured_value, sanitize_event, ) -from posthog.mcp._sink import McpCaptureOptions, process_mcp_event +from posthog.capture_event import _to_v1_event +from posthog.client import Client +from posthog.mcp._sink import McpCaptureOptions, McpEventSink, process_mcp_event +from posthog.test.capture_helpers import patch_capture_send, sent_events from posthog.mcp._truncation import MAX_EVENT_BYTES, normalize, truncate_event +from posthog.mcp import McpAnalytics, _NoopAnalytics +from posthog.mcp._instrumentation import ( + _maybe_emit_initialize, + record_feedback, + record_initialize, + record_missing_capability, + record_resource_request, + record_tool_call, + record_tools_list, +) +from posthog.mcp._internal import MCPAnalyticsData, set_server_tracking_data +from posthog.mcp.logger import set_logger +from posthog.mcp.types import FeedbackReport, MCPAnalyticsOptions, UserIdentity +from posthog.test.mcp._helpers import FakeClient, flush_background # --- ids --------------------------------------------------------------------- @@ -1027,7 +1045,8 @@ def test_build_tool_call_event_properties(): assert props[PostHogMCPAnalyticsProperty.LLM_MODEL_SOURCE] == "client_metadata" assert props[PostHogMCPAnalyticsProperty.SESSION_ID] == "ses_abc" # anonymous (no identity) => person processing disabled - assert props["$process_person_profile"] is False + assert capture["options"] == {"process_person_profile": False} + assert "$process_person_profile" not in props def test_protocol_version_on_primary_and_exception_events(): @@ -1058,14 +1077,37 @@ def test_identity_enables_person_processing_and_set(): "identify_actor_given_id": "user_1", "identify_actor_data": {"email": "a@b.com"}, "groups": {"organization": "org_1"}, + "properties": {"$groups": {"organization": "custom", "project": "p1"}}, "timestamp": datetime.now(timezone.utc), } [capture] = build_posthog_capture_events(event) props = capture["properties"] assert capture["distinct_id"] == "user_1" - assert "$process_person_profile" not in props + assert capture["options"] == {} assert props["$set"] == {"email": "a@b.com"} - assert props["$groups"] == {"organization": "org_1"} + assert props["$groups"] == {"organization": "org_1", "project": "p1"} + + +def test_typed_groups_win_on_primary_and_exception_events(): + event = { + "event_type": MCPAnalyticsEventType.MCP_TOOLS_CALL, + "session_id": "ses_abc", + "is_error": True, + "error": {"$exception_list": [{"type": "ValueError", "value": "boom"}]}, + "groups": {"organization": "org_1"}, + "properties": {"$groups": {"organization": "custom", "project": "p1"}}, + "timestamp": datetime.now(timezone.utc), + } + captures = build_posthog_capture_events(event) + assert [c["event"] for c in captures] == [ + PostHogMCPAnalyticsEvent.TOOL_CALL, + PostHogMCPAnalyticsEvent.EXCEPTION, + ] + for capture in captures: + assert capture["properties"]["$groups"] == { + "organization": "org_1", + "project": "p1", + } def test_listed_tool_names_only_on_tools_list(): @@ -1241,3 +1283,373 @@ async def before_send(e): result = await process_mcp_event(event, McpCaptureOptions(before_send=before_send)) _, captures = result assert captures[0]["properties"]["added"] is True + + +def _opt_in(e): + return {**e, "options": {"process_person_profile": True}} + + +@pytest.mark.parametrize( + "before_send, expected", + [(None, False), (_opt_in, True)], + ids=["sdk_option_wins", "before_send_can_change_it"], +) +async def test_anonymous_event_sends_personless_option(before_send, expected): + event = { + "event_type": MCPAnalyticsEventType.MCP_TOOLS_CALL, + "session_id": "ses_abc", + "properties": {"$process_person_profile": True}, + "timestamp": datetime.now(timezone.utc), + } + with patch_capture_send("client") as send: + client = Client( + "test-key", + sync_mode=True, + super_options={"process_person_profile": True}, + ) + await McpEventSink(client).capture( + event, McpCaptureOptions(before_send=before_send) + ) + [wire] = [_to_v1_event(msg) for msg in sent_events(send)] + assert wire["options"] == {"process_person_profile": expected} + + +# --- event options ----------------------------------------------------------- + + +def _options_event(identified, **fields): + event = { + "event_type": MCPAnalyticsEventType.MCP_TOOLS_CALL, + "session_id": "ses_abc", + "resource_name": "broken_tool", + "is_error": True, + "error": capture_exception(ValueError("boom")), + "timestamp": datetime.now(timezone.utc), + **fields, + } + if identified: + event["identify_actor_given_id"] = "user_1" + return event + + +@pytest.mark.parametrize( + "identified, callback, per_call, expected", + [ + (True, None, None, {}), + (True, None, {"cookieless_mode": True}, {"cookieless_mode": True}), + (True, {"cookieless_mode": True}, None, {"cookieless_mode": True}), + ( + True, + {"product_tour_id": "callback", "cookieless_mode": True}, + {"product_tour_id": "call"}, + {"product_tour_id": "call", "cookieless_mode": True}, + ), + ( + True, + {"process_person_profile": False}, + {"process_person_profile": True}, + {"process_person_profile": True}, + ), + (False, None, None, {"process_person_profile": False}), + ( + False, + None, + {"process_person_profile": True, "cookieless_mode": True}, + {"process_person_profile": False, "cookieless_mode": True}, + ), + ( + False, + {"process_person_profile": True}, + None, + {"process_person_profile": False}, + ), + ], + ids=[ + "identified_without_options", + "identified_per_call", + "identified_callback", + "per_call_beats_callback_key_by_key", + "identified_keeps_user_values", + "anonymous_without_options", + "anonymous_personless_beats_per_call", + "anonymous_personless_beats_callback", + ], +) +def test_event_options_layering(identified, callback, per_call, expected): + callers = copy.deepcopy((callback, per_call)) + event = _options_event( + identified, callback_event_options=callback, event_options=per_call + ) + captures = build_posthog_capture_events(event) + + assert [c["event"] for c in captures] == [ + PostHogMCPAnalyticsEvent.TOOL_CALL, + PostHogMCPAnalyticsEvent.EXCEPTION, + ] + assert [c["options"] for c in captures] == [expected, expected] + # Each event gets its own copy, so before_send can change one alone. + assert captures[0]["options"] is not captures[1]["options"] + assert not any(k.startswith("$") for k in captures[0]["options"]) + # The caller's dicts are copied, never changed. + assert (callback, per_call) == callers + + +@pytest.mark.parametrize( + "field, message", + [ + ( + "event_options", + "event_options must be a dict, got str. Sending the event without them.", + ), + ( + "callback_event_options", + "The event_options callback result must be a dict, got list. " + "Sending the event without them.", + ), + ], +) +def test_non_dict_event_options_are_logged_and_ignored(field, message, caplog): + value = "process_person_profile" if field == "event_options" else ["x"] + event = _options_event(True, **{field: value}) + + with caplog.at_level("WARNING", logger="posthog.mcp"): + captures = build_posthog_capture_events(event) + + assert [c["options"] for c in captures] == [{}, {}] + # Checked once per event, not once per payload. + assert [r.getMessage() for r in caplog.records] == [message] + + +async def test_before_send_sees_merged_event_options(): + seen = [] + + def before_send(capture): + seen.append(dict(capture["options"])) + return capture + + event = _options_event( + False, + callback_event_options={"cookieless_mode": True}, + event_options={"process_person_profile": True, "product_tour_id": "t"}, + ) + await process_mcp_event(event, McpCaptureOptions(before_send=before_send)) + + expected = { + "cookieless_mode": True, + "product_tour_id": "t", + "process_person_profile": False, + } + assert seen == [expected, expected] + + +@pytest.mark.parametrize( + "identified, expected", + [ + (True, {"cookieless_mode": True, "process_person_profile": True}), + (False, {"cookieless_mode": True, "process_person_profile": False}), + ], + ids=["identified", "anonymous"], +) +async def test_event_options_reach_the_v1_payload(identified, expected): + event = _options_event( + identified, + is_error=False, + error=None, + event_options={"cookieless_mode": True, "process_person_profile": True}, + ) + with patch_capture_send("client") as send: + client = Client("test-key", sync_mode=True) + await McpEventSink(client).capture(event, McpCaptureOptions()) + [wire] = [_to_v1_event(msg) for msg in sent_events(send)] + assert wire["options"] == expected + assert not any(k.startswith("$") for k in wire["options"]) + assert "$process_person_profile" not in wire["properties"] + assert "$cookieless_mode" not in wire["properties"] + + +async def _record_every_event_type(data, session_id): + """Drive every auto-capture call site that runs ``event_properties``.""" + now = datetime.now(timezone.utc) + await record_initialize( + data, + session_id=session_id, + params={"clientInfo": {"name": "c"}}, + result=None, + extra=None, + timestamp=now, + ) + # The first-request stand-in for an initialize nothing observed. + await _maybe_emit_initialize(data, "ses_first", "generated", None, None, None) + await record_tool_call( + data, session_id, name="broken", arguments={}, error=RuntimeError("boom") + ) + await record_missing_capability( + data, session_id, tool_name="get_more_tools", context="csv", arguments={} + ) + await record_feedback( + data, + session_id, + report=FeedbackReport(summary="good"), + tool_name="send_feedback", + arguments={}, + ) + await record_tools_list( + data, session_id, names=["a"], request={"method": "tools/list"} + ) + for event_type, method in ( + (MCPAnalyticsEventType.MCP_RESOURCES_LIST, "resources/list"), + (MCPAnalyticsEventType.MCP_RESOURCES_READ, "resources/read"), + ): + await record_resource_request( + data, + session_id, + event_type=event_type, + request={"method": method, "params": {"uri": "file:///a"}}, + ) + await flush_background() + + +_EVERY_AUTO_CAPTURED_EVENT = [ + PostHogMCPAnalyticsEvent.INITIALIZE, + PostHogMCPAnalyticsEvent.INITIALIZE, + PostHogMCPAnalyticsEvent.TOOL_CALL, + PostHogMCPAnalyticsEvent.EXCEPTION, + PostHogMCPAnalyticsEvent.MISSING_CAPABILITY, + PostHogMCPAnalyticsEvent.FEEDBACK, + PostHogMCPAnalyticsEvent.TOOLS_LIST, + PostHogMCPAnalyticsEvent.RESOURCES_LIST, + PostHogMCPAnalyticsEvent.RESOURCE_READ, +] + + +def _sync_options(request, extra): + return {"process_person_profile": True, "cookieless_mode": True} + + +async def _async_options(request, extra): + return _sync_options(request, extra) + + +@pytest.mark.parametrize("callback", [_sync_options, _async_options]) +@pytest.mark.parametrize( + "identified, expected", + [ + (True, {"process_person_profile": True, "cookieless_mode": True}), + (False, {"process_person_profile": False, "cookieless_mode": True}), + ], + ids=["identified", "anonymous"], +) +async def test_event_options_callback_applies_to_every_auto_captured_event( + callback, identified, expected +): + requests = [] + + def recording(request, extra): + requests.append(request.get("method")) + return callback(request, extra) + + client = FakeClient() + data = MCPAnalyticsData( + options=MCPAnalyticsOptions(event_options=recording), + sink=McpEventSink(client), + ) + if identified: + for session_id in ("ses_abc", "ses_first"): + data.identified_sessions.set(session_id, UserIdentity("user_1")) + + await _record_every_event_type(data, "ses_abc") + + assert [e["event"] for e in client.events] == _EVERY_AUTO_CAPTURED_EVENT + assert [e["options"] for e in client.events] == [expected] * len(client.events) + # One call per MCP request, with that request. + assert requests == [ + "initialize", + "initialize", + "tools/call", + "tools/call", + "tools/call", + "tools/list", + "resources/list", + "resources/read", + ] + + +def _raise(request, extra): + raise RuntimeError("callback failed") + + +@pytest.mark.parametrize( + "callback, log_line", + [ + ( + lambda request, extra: "nope", + "The event_options callback result must be a dict, got str. " + "Sending the event without them.", + ), + ( + lambda request, extra: 0, + "The event_options callback result must be a dict, got int. " + "Sending the event without them.", + ), + (_raise, "event_options callback error: callback failed"), + ], + ids=["non_dict", "falsy_non_dict", "raises"], +) +async def test_failed_event_options_callback_still_sends_events(callback, log_line): + logged = [] + set_logger(logged.append) + try: + client = FakeClient() + data = MCPAnalyticsData( + options=MCPAnalyticsOptions(event_options=callback), + sink=McpEventSink(client), + ) + await _record_every_event_type(data, "ses_abc") + finally: + set_logger(None) + + assert [e["event"] for e in client.events] == _EVERY_AUTO_CAPTURED_EVENT + assert [e["options"] for e in client.events] == [ + {"process_person_profile": False} + ] * len(client.events) + assert log_line in logged + + +class _ServerKey: + """A weakly referenceable stand-in for an instrumented server.""" + + +@pytest.mark.parametrize( + "identified, expected", + [ + (True, {"cookieless_mode": True, "process_person_profile": True}), + (False, {"cookieless_mode": True, "process_person_profile": False}), + ], + ids=["identified", "anonymous"], +) +async def test_analytics_capture_sends_event_options(identified, expected): + client = FakeClient() + key = _ServerKey() + data = MCPAnalyticsData( + options=MCPAnalyticsOptions(), sink=McpEventSink(client), session_id="ses" + ) + if identified: + data.identified_sessions.set("ses", UserIdentity("user_1")) + set_server_tracking_data(key, data) + + await McpAnalytics(key).capture( + "feedback_submitted", + {"rating": 5}, + event_options={"cookieless_mode": True, "process_person_profile": True}, + ) + + [event] = client.events + assert event["event"] == "feedback_submitted" + assert event["options"] == expected + + +async def test_noop_analytics_capture_accepts_event_options(): + assert ( + await _NoopAnalytics().capture("e", event_options={"cookieless_mode": True}) + is None + ) diff --git a/posthog/test/mcp/test_posthog_mcp.py b/posthog/test/mcp/test_posthog_mcp.py index 76c724bb6..c92559284 100644 --- a/posthog/test/mcp/test_posthog_mcp.py +++ b/posthog/test/mcp/test_posthog_mcp.py @@ -9,8 +9,8 @@ import pytest from mcp.types import CallToolResult, ServerResult, TextContent, Tool -from posthog.capture_mode import CaptureMode from posthog.mcp import ( + FeedbackReport, PostHogMCP, PreparedToolCall, derive_session_id_from_conversation, @@ -111,98 +111,81 @@ def before_send(event): assert captured[2]["properties"]["$mcp_server_build"] == "default-build" -async def test_mcp_events_use_mcp_library_identity(): - captured = [] - - def before_send(event): - captured.append(event) - return event - - client = PostHogMCP( - "phc_test", - host="https://us.i.posthog.com", - send=False, - before_send=before_send, - ) - client.capture_tool_call("broken", is_error=True, error=RuntimeError("kaboom")) - await _flush() - - assert {event["event"] for event in captured} == {"$mcp_tool_call", "$exception"} - assert all( - event["properties"]["$lib"] == "posthog-python-mcp" - and event["properties"]["$lib_version"] == VERSION - for event in captured - ) - - -def test_mcp_library_identity_reaches_capture_v0_header(): - response = mock.Mock(status_code=200) +def test_mcp_client_keeps_the_sdk_identity(): client = PostHogMCP("phc_test", sync_mode=True) - - with mock.patch("posthog.request._session.post", return_value=response) as post: - client.capture("$mcp_custom") - - assert post.call_args.kwargs["headers"]["User-Agent"] == ( - f"posthog-python-mcp/{VERSION}" - ) - - -def test_mcp_library_identity_reaches_capture_v1_header(): - client = PostHogMCP("phc_test", sync_mode=True, capture_mode=CaptureMode.V1) with mock.patch("posthog.client._send_v1_batch") as send: client.capture("$mcp_custom") - assert send.call_args.kwargs["sdk_info"] == f"posthog-python-mcp/{VERSION}" - event = send.call_args.args[2][0] - assert event["properties"]["$lib"] == "posthog-python-mcp" - assert event["properties"]["$lib_version"] == VERSION + assert send.call_args.kwargs["sdk_info"] == f"posthog-python/{VERSION}" -def test_mcp_library_identity_reaches_feature_flag_requests(): - response = mock.Mock(status_code=200) - response.json.return_value = {"flags": {}} - client = PostHogMCP("phc_test", send=False) +_CAPTURE_METHODS = [ + ("capture_tool_call", ("search",), {}, "$mcp_tool_call"), + ("capture_initialize", (), {}, "$mcp_initialize"), + ("capture_tools_list", (), {"tool_names": ["a"]}, "$mcp_tools_list"), + ("capture_missing_capability", (), {}, "$mcp_missing_capability"), + ( + "capture_feedback", + (), + {"report": FeedbackReport(summary="good")}, + "$mcp_feedback", + ), +] - with mock.patch( - "posthog.request._flags_session.post", return_value=response - ) as post: - client.evaluate_flags("user_1") - assert post.call_args.kwargs["headers"]["User-Agent"] == ( - f"posthog-python-mcp/{VERSION}" +@pytest.mark.parametrize( + "method, args, kwargs, event_name", + _CAPTURE_METHODS, + ids=[m[0] for m in _CAPTURE_METHODS], +) +@pytest.mark.parametrize( + "distinct_id, expected", + [ + ("user_1", {"cookieless_mode": True, "process_person_profile": True}), + (None, {"cookieless_mode": True, "process_person_profile": False}), + ], + ids=["identified", "anonymous"], +) +async def test_capture_methods_send_event_options( + method, args, kwargs, event_name, distinct_id, expected +): + client, captured = make_client() + event_options = {"cookieless_mode": True, "process_person_profile": True} + getattr(client, method)( + *args, distinct_id=distinct_id, event_options=event_options, **kwargs ) + await _flush() + [event] = captured + assert event["event"] == event_name + assert event["options"] == expected + assert event_options == {"cookieless_mode": True, "process_person_profile": True} -def test_mcp_library_identity_reaches_feature_flag_definition_requests(): - response = mock.Mock(status_code=200, headers={}) - response.json.return_value = {"flags": [], "group_type_mapping": {}, "cohorts": {}} - client = PostHogMCP( - "phc_test", - secret_key="phs_test", - send=False, - enable_local_evaluation=False, - ) - - with mock.patch("posthog.request._session.get", return_value=response) as get: - client.load_feature_flags() - assert get.call_args.kwargs["headers"]["User-Agent"] == ( - f"posthog-python-mcp/{VERSION}" +async def test_capture_tool_call_event_options_reach_the_exception_sibling(): + client, captured = make_client() + client.capture_tool_call( + "broken", + is_error=True, + error=RuntimeError("kaboom"), + distinct_id="u", + event_options={"product_tour_id": "tour"}, ) - client.shutdown() + await _flush() + assert [(e["event"], e["options"]) for e in captured] == [ + ("$mcp_tool_call", {"product_tour_id": "tour"}), + ("$exception", {"product_tour_id": "tour"}), + ] -def test_mcp_library_identity_reaches_remote_config_requests(): - response = mock.Mock(status_code=200, headers={}) - response.json.return_value = "payload" - client = PostHogMCP("phc_test", secret_key="phs_test", send=False) - with mock.patch("posthog.request._session.get", return_value=response) as get: - assert client.get_remote_config_payload("flag-key") == "payload" +async def test_capture_methods_pass_empty_options_without_event_options(): + client, captured = make_client() + client.capture_tool_call("search", distinct_id="u") + await _flush() - assert get.call_args.kwargs["headers"]["User-Agent"] == ( - f"posthog-python-mcp/{VERSION}" - ) + [event] = captured + assert event["options"] == {} async def test_capture_initialize_and_tools_list(): diff --git a/posthog/test/mcp/test_v2_mcpserver.py b/posthog/test/mcp/test_v2_mcpserver.py index 4e7a5d2c1..5b3ba1cb3 100644 --- a/posthog/test/mcp/test_v2_mcpserver.py +++ b/posthog/test/mcp/test_v2_mcpserver.py @@ -536,7 +536,8 @@ async def test_anonymous_events_do_not_create_person_profiles(): await _flush() calls = _events(client, "$mcp_tool_call") - assert calls[0]["properties"]["$process_person_profile"] is False + assert calls[0]["options"] == {"process_person_profile": False} + assert "$process_person_profile" not in calls[0]["properties"] async def test_a_failed_registry_lookup_delegates_instead_of_swallowing(): diff --git a/posthog/test/released_flags_scenarios.py b/posthog/test/released_flags_scenarios.py index 2e8246191..1bdbb9e22 100644 --- a/posthog/test/released_flags_scenarios.py +++ b/posthog/test/released_flags_scenarios.py @@ -31,7 +31,6 @@ ) API_KEY = "phc_released_flags_scenarios" DISTINCT_ID = "user-1" -ACCEPTED_UUID = "70000000-0000-4000-8000-000000000000" REQUEST_ID = "60000000-0000-4000-8000-000000000000" EVALUATED_AT = 1800000000000 MATCHED = { @@ -170,15 +169,17 @@ def flags(*args: Any, **kwargs: Any) -> Any: raise response return copy.deepcopy(response) - def enqueue(message: Dict[str, Any], *args: Any, **kwargs: Any) -> Optional[str]: + # Read the built event in before_send: v1 layers flag properties inside _enqueue. + def record(message: Dict[str, Any]) -> Optional[Dict[str, Any]]: events.append([message["event"], _flag_event_properties(message)]) - # Accept the event, as the real queue does, by returning an event UUID. - return ACCEPTED_UUID + # Keep the event, so capture accepts it and returns its UUID as the real + # queue does; flag events dedupe only events that were accepted. + return message try: with ( mock.patch("posthog.client.flags", side_effect=flags), - mock.patch.object(client, "_enqueue", side_effect=enqueue), + mock.patch.object(client, "before_send", record), warnings.catch_warnings(), ): warnings.simplefilter("ignore") diff --git a/posthog/test/snapshots/legacy_event_family.json b/posthog/test/snapshots/event_family.json similarity index 69% rename from posthog/test/snapshots/legacy_event_family.json rename to posthog/test/snapshots/event_family.json index 4e33c6bd8..98f2dc28a 100644 --- a/posthog/test/snapshots/legacy_event_family.json +++ b/posthog/test/snapshots/event_family.json @@ -1,10 +1,10 @@ { "body": { - "api_key": "phc_snapshot_project", "batch": [ { "distinct_id": "user-123", "event": "order completed", + "options": {}, "properties": { "$geoip_disable": true, "$groups": { @@ -30,28 +30,34 @@ } ] }, - "timestamp": "2026-01-02T03:04:05+00:00", + "timestamp": "2026-01-02T03:04:05.000000+00:00", "uuid": "00000000-0000-4000-8000-000000000001" }, { - "$set": { - "email": "person@example.com", - "plan": "pro" - }, "distinct_id": "user-123", "event": "$set", + "options": { + "process_person_profile": true + }, "properties": { "$geoip_disable": true, "$is_server": true, "$lib": "posthog-python", - "$lib_version": "" + "$lib_version": "", + "$set": { + "email": "person@example.com", + "plan": "pro" + } }, - "timestamp": "2026-01-02T03:04:05+00:00", + "timestamp": "2026-01-02T03:04:05.000000+00:00", "uuid": "00000000-0000-4000-8000-000000000002" }, { "distinct_id": "anonymous-789", "event": "$create_alias", + "options": { + "process_person_profile": true + }, "properties": { "$geoip_disable": true, "$is_server": true, @@ -60,12 +66,15 @@ "alias": "user-123", "distinct_id": "anonymous-789" }, - "timestamp": "2026-01-02T03:04:05+00:00", + "timestamp": "2026-01-02T03:04:05.000000+00:00", "uuid": "00000000-0000-4000-8000-000000000003" }, { "distinct_id": "user-123", "event": "$groupidentify", + "options": { + "process_person_profile": true + }, "properties": { "$geoip_disable": true, "$group_key": "company-456", @@ -78,17 +87,21 @@ "$lib": "posthog-python", "$lib_version": "" }, - "timestamp": "2026-01-02T03:04:05+00:00", + "timestamp": "2026-01-02T03:04:05.000000+00:00", "uuid": "00000000-0000-4000-8000-000000000004" } ], - "historical_migration": false, - "sent_at": "2026-01-02T03:04:05+00:00" + "created_at": "2026-01-02T03:04:05.000000+00:00" }, "headers": { + "Authorization": "Bearer phc_snapshot_project", "Content-Type": "application/json", + "PostHog-Attempt": "1", + "PostHog-Request-Id": "", + "PostHog-Request-Timestamp": "2026-01-02T03:04:05.000000+00:00", + "PostHog-Sdk-Info": "posthog-python/", "User-Agent": "posthog-python/" }, "timeout": 15, - "url": "https://example.posthog.test/batch/" + "url": "https://example.posthog.test/i/v1/analytics/events" } diff --git a/posthog/test/snapshots/exception_event.json b/posthog/test/snapshots/exception_event.json index aef9d628e..34edbee40 100644 --- a/posthog/test/snapshots/exception_event.json +++ b/posthog/test/snapshots/exception_event.json @@ -1,10 +1,10 @@ { "body": { - "api_key": "phc_snapshot_project", "batch": [ { "distinct_id": "user-123", "event": "$exception", + "options": {}, "properties": { "$exception_level": "error", "$exception_list": [ @@ -56,7 +56,7 @@ "", "def _exception_request():", " session = mock.MagicMock()", - " session.post.return_value = _successful_response()" + " session.post.side_effect = _capture_ok_response" ], "pre_context": [ "", @@ -129,17 +129,21 @@ "component": "checkout", "severity": "high" }, - "timestamp": "2026-01-02T03:04:05+00:00", + "timestamp": "2026-01-02T03:04:05.000000+00:00", "uuid": "00000000-0000-4000-8000-000000000005" } ], - "historical_migration": false, - "sent_at": "2026-01-02T03:04:05+00:00" + "created_at": "2026-01-02T03:04:05.000000+00:00" }, "headers": { + "Authorization": "Bearer phc_snapshot_project", "Content-Type": "application/json", + "PostHog-Attempt": "1", + "PostHog-Request-Id": "", + "PostHog-Request-Timestamp": "2026-01-02T03:04:05.000000+00:00", + "PostHog-Sdk-Info": "posthog-python/", "User-Agent": "posthog-python/" }, "timeout": 15, - "url": "https://example.posthog.test/batch/" + "url": "https://example.posthog.test/i/v1/analytics/events" } diff --git a/posthog/test/test_ai_capture_lane.py b/posthog/test/test_ai_capture_lane.py index 3ab2f9f87..dd1843803 100644 --- a/posthog/test/test_ai_capture_lane.py +++ b/posthog/test/test_ai_capture_lane.py @@ -1,23 +1,34 @@ +import os import threading import unittest import uuid from unittest import mock +import pytest +from parameterized import parameterized + import posthog -from posthog.ai.utils import _capture_ai_event, finalize_ai_content, with_privacy_mode -from posthog.capture_mode import CaptureMode +from posthog.ai.utils import ( + _capture_ai_event, + _resolve_ai_client, + finalize_ai_content, + with_privacy_mode, +) +from posthog.async_client import AsyncPosthog +from posthog.capture_compression import CAPTURE_COMPRESSION_ENV_VAR, CaptureCompression from posthog.client import Client -from posthog.consumer import AI_MAX_MSG_SIZE, MAX_MSG_SIZE -from posthog.request import AI_EVENTS_ENDPOINT, EVENTS_ENDPOINT +from posthog.consumer import AI_MAX_MSG_SIZE, AI_MAX_PROPERTIES_SIZE, MAX_MSG_SIZE +from posthog.capture_send import _CAPTURE_AI_V1_PATH, _CAPTURE_V1_PATH from posthog.version import VERSION +from posthog.test.capture_helpers import patch_capture_send, sent_batch from posthog.test.test_utils import TEST_API_KEY -def _events_by_path(mock_post): +def _events_by_path(mock_send): by_path: dict[str, list] = {} - for call in mock_post.call_args_list: - by_path.setdefault(call.kwargs["path"], []).extend(call.kwargs["batch"]) + for index, call in enumerate(mock_send.call_args_list): + by_path.setdefault(call.kwargs["path"], []).extend(sent_batch(mock_send, index)) return by_path @@ -29,24 +40,24 @@ def _client(self, **kwargs): def test_capture_ai_and_capture_ride_separate_lanes(self): client = self._client() - with mock.patch("posthog.consumer.batch_post") as mock_post: + with patch_capture_send("consumer") as mock_post: client.capture("button_clicked", distinct_id="d") client.capture_ai("$ai_generation", distinct_id="d") client.flush() by_path = _events_by_path(mock_post) - self.assertEqual(set(by_path), {EVENTS_ENDPOINT, AI_EVENTS_ENDPOINT}) + self.assertEqual(set(by_path), {_CAPTURE_V1_PATH, _CAPTURE_AI_V1_PATH}) self.assertEqual( - [e["event"] for e in by_path[EVENTS_ENDPOINT]], ["button_clicked"] + [e["event"] for e in by_path[_CAPTURE_V1_PATH]], ["button_clicked"] ) self.assertEqual( - [e["event"] for e in by_path[AI_EVENTS_ENDPOINT]], ["$ai_generation"] + [e["event"] for e in by_path[_CAPTURE_AI_V1_PATH]], ["$ai_generation"] ) - for call in mock_post.call_args_list: - events = {e["event"] for e in call.kwargs["batch"]} + for index, call in enumerate(mock_post.call_args_list): + events = {e["event"] for e in sent_batch(mock_post, index)} expected = ( {"$ai_generation"} - if call.kwargs["path"] == AI_EVENTS_ENDPOINT + if call.kwargs["path"] == _CAPTURE_AI_V1_PATH else {"button_clicked"} ) self.assertEqual(events, expected) @@ -55,13 +66,13 @@ def test_capture_does_not_reroute_ai_named_events(self): # The two-lane rule: `capture()` never special-cases AI events, no # matter their name. Only `capture_ai()` reaches the AI lane. client = self._client() - with mock.patch("posthog.consumer.batch_post") as mock_post: + with patch_capture_send("consumer") as mock_post: client.capture("$ai_generation", distinct_id="d") client.flush() self.assertEqual( [call.kwargs["path"] for call in mock_post.call_args_list], - [EVENTS_ENDPOINT], + [_CAPTURE_V1_PATH], ) def test_capture_ai_returns_event_uuid_like_capture(self): @@ -71,22 +82,14 @@ def test_capture_ai_returns_event_uuid_like_capture(self): def test_sync_mode_capture_ai_posts_single_event_batch_to_ai_endpoint(self): client = Client(TEST_API_KEY, sync_mode=True) - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client.capture_ai("$ai_generation", distinct_id="d") mock_post.assert_called_once() - self.assertEqual(mock_post.call_args.kwargs["path"], AI_EVENTS_ENDPOINT) - batch = mock_post.call_args.kwargs["batch"] + self.assertEqual(mock_post.call_args.kwargs["path"], _CAPTURE_AI_V1_PATH) + batch = sent_batch(mock_post) self.assertEqual([e["event"] for e in batch], ["$ai_generation"]) - def test_multimodal_client_routes_wrapper_captures_to_ai_lane(self): - client = self._client(enable_full_ai_capture=True) - with mock.patch("posthog.consumer.batch_post") as mock_post: - _capture_ai_event(client, "$ai_generation", distinct_id="d") - client.flush() - by_path = _events_by_path(mock_post) - self.assertEqual(set(by_path), {AI_EVENTS_ENDPOINT}) - def test_disabled_client_never_starts_ai_lane(self): client = Client(TEST_API_KEY, disabled=True) client.capture_ai("$ai_generation", distinct_id="d") @@ -113,7 +116,6 @@ def test_analytics_consumers_keep_todays_parameters(self): thread=2, flush_at=7, flush_interval=0.5, - gzip=True, max_retries=4, timeout=9, historical_migration=True, @@ -122,29 +124,27 @@ def test_analytics_consumers_keep_todays_parameters(self): self.assertEqual(len(consumers), 2) for consumer in consumers: self.assertIs(consumer.queue, client.queue) - self.assertEqual(consumer.endpoint, EVENTS_ENDPOINT) + self.assertEqual(consumer.endpoint, _CAPTURE_V1_PATH) self.assertEqual(consumer.max_msg_size, MAX_MSG_SIZE) self.assertEqual(consumer.flush_at, 7) self.assertEqual(consumer.flush_interval, 0.5) - self.assertTrue(consumer.gzip) self.assertEqual(consumer.retries, 4) self.assertEqual(consumer.timeout, 9) self.assertTrue(consumer.historical_migration) - self.assertEqual(consumer.capture_mode, client.capture_mode) self.assertEqual(consumer.capture_compression, client.capture_compression) client.join() def test_analytics_traffic_posts_to_single_endpoint(self): client = Client(TEST_API_KEY, flush_interval=0.05) - with mock.patch("posthog.consumer.batch_post") as mock_post: + with patch_capture_send("consumer") as mock_post: client.capture("event_a", distinct_id="d") client.capture("event_b", distinct_id="d") client.flush() by_path = _events_by_path(mock_post) - self.assertEqual(set(by_path), {EVENTS_ENDPOINT}) + self.assertEqual(set(by_path), {_CAPTURE_V1_PATH}) self.assertEqual( - sorted(e["event"] for e in by_path[EVENTS_ENDPOINT]), + sorted(e["event"] for e in by_path[_CAPTURE_V1_PATH]), ["event_a", "event_b"], ) client.join() @@ -152,9 +152,9 @@ def test_analytics_traffic_posts_to_single_endpoint(self): def test_sync_mode_analytics_path_unchanged(self): client = Client(TEST_API_KEY, sync_mode=True) self.assertIsNone(client.consumers) - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client.capture("button_clicked", distinct_id="d") - self.assertEqual(mock_post.call_args.kwargs["path"], EVENTS_ENDPOINT) + self.assertEqual(mock_post.call_args.kwargs["path"], _CAPTURE_V1_PATH) class TestLaneSizeCaps(unittest.TestCase): @@ -176,64 +176,216 @@ def test_ai_lane_accepts_multi_megabyte_events(self): batch = consumer.next() self.assertEqual([e["event"] for e in batch], ["$ai_generation"]) - def test_ai_lane_drops_events_over_its_cap(self): - client = self._client() + @parameterized.expand( + [ + ("properties_at_endpoint_ceiling", {}, AI_MAX_PROPERTIES_SIZE, True), + ("over_guard", {}, AI_MAX_MSG_SIZE, False), + ( + "over_lowered_cap", + {"capture_ai_max_event_bytes": 1024 * 1024}, + 2 * 1024 * 1024, + False, + ), + ] + ) + def test_ai_lane_size_guard(self, _name, config, payload_bytes, accepted): + client = Client(TEST_API_KEY, send=False, flush_interval=0.05, **config) client._ai_lane.start() consumer = client._ai_lane.consumers[0] - client._ai_lane.queue.put(self._sized_event("$ai_generation", AI_MAX_MSG_SIZE)) - self.assertEqual(consumer.next(), []) + client._ai_lane.queue.put(self._sized_event("$ai_generation", payload_bytes)) + self.assertEqual( + [e["event"] for e in consumer.next()], + ["$ai_generation"] if accepted else [], + ) self.assertTrue(client._ai_lane.queue.empty()) - def test_analytics_lane_rejects_events_over_900kib(self): + def test_sync_mode_ai_event_over_cap_is_not_sent(self): + client = Client( + TEST_API_KEY, sync_mode=True, capture_ai_max_event_bytes=1024 * 1024 + ) + with patch_capture_send("client") as mock_send: + with self.assertLogs("posthog", level="ERROR") as logs: + result = client.capture_ai( + "$ai_generation", + distinct_id="d", + properties={"p": "x" * (2 * 1024 * 1024)}, + ) + + self.assertIsNone(result) + mock_send.assert_not_called() + self.assertIn("exceeds the 1024KiB limit", "\n".join(logs.output)) + + def test_sync_mode_ai_event_at_endpoint_ceiling_is_sent(self): + client = Client(TEST_API_KEY, sync_mode=True) + with patch_capture_send("client") as mock_send: + result = client.capture_ai( + "$ai_generation", + distinct_id="d", + properties={"p": "x" * AI_MAX_PROPERTIES_SIZE}, + ) + + self.assertIsNotNone(result) + mock_send.assert_called_once() + + def test_analytics_lane_sends_events_up_to_the_request_limit(self): + # Capture reports an analytics event over its per-event limit in the + # response, so the SDK only drops what no request could carry. client = self._client() consumer = client.consumers[0] - client.queue.put(self._sized_event("big_analytics_event", 2 * 1024 * 1024)) + big = self._sized_event("big_analytics_event", 2 * 1024 * 1024) + client.queue.put(big) + client.queue.put(self._sized_event("too_big_for_a_request", MAX_MSG_SIZE)) + self.assertEqual(consumer.next(), [big]) self.assertEqual(consumer.next(), []) self.assertTrue(client.queue.empty()) -class TestAiLaneV0Pinned(unittest.TestCase): - """The AI endpoint has no v1 form: the AI lane ignores `capture_mode=v1`.""" +class TestAiLaneWireConfig(unittest.TestCase): + """The AI lane has its own endpoint, compression, timeout, queue and size + guard, independent of the analytics lane's settings.""" - def test_ai_lane_consumers_pin_v0_and_ai_endpoint(self): - client = Client(TEST_API_KEY, send=False, capture_mode="v1", thread=2) + @parameterized.expand( + [ + ("defaults", {}, CaptureCompression.NONE, 30, 1000, AI_MAX_MSG_SIZE), + ( + "configured", + { + "capture_ai_compression": "zstd", + "capture_ai_timeout": 45, + "capture_ai_max_queue_size": 50, + "capture_ai_max_event_bytes": 1024 * 1024, + }, + CaptureCompression.ZSTD, + 45, + 50, + 1024 * 1024, + ), + ] + ) + def test_ai_lane_consumers_use_ai_config( + self, _name, config, compression, timeout, queue_size, max_event_bytes + ): + with mock.patch.dict(os.environ, {CAPTURE_COMPRESSION_ENV_VAR: "deflate"}): + client = Client( + TEST_API_KEY, + send=False, + capture_compression="gzip", + timeout=9, + max_queue_size=77, + thread=2, + **config, + ) client._ai_lane.start() + self.assertEqual(client._ai_lane.queue.maxsize, queue_size) self.assertEqual(len(client._ai_lane.consumers), 2) for consumer in client._ai_lane.consumers: self.assertIs(consumer.queue, client._ai_lane.queue) - self.assertEqual(consumer.endpoint, AI_EVENTS_ENDPOINT) - self.assertEqual(consumer.max_msg_size, AI_MAX_MSG_SIZE) - self.assertEqual(consumer.capture_mode, CaptureMode.V0) - - def test_async_ai_events_use_v0_even_with_capture_mode_v1(self): - client = Client(TEST_API_KEY, capture_mode="v1", flush_interval=0.05) - with ( - mock.patch("posthog.consumer.batch_post") as mock_post, - mock.patch("posthog.consumer._send_v1_batch") as mock_v1, - ): + self.assertEqual(consumer.endpoint, _CAPTURE_AI_V1_PATH) + self.assertEqual(consumer.max_msg_size, max_event_bytes) + self.assertEqual(consumer.capture_compression, compression) + self.assertEqual(consumer.timeout, timeout) + self.assertEqual(client.queue.maxsize, 77) + for consumer in client._analytics_lane.consumers: + self.assertEqual(consumer.capture_compression, CaptureCompression.GZIP) + self.assertEqual(consumer.timeout, 9) + client.join() + + @parameterized.expand( + [ + ( + "event_bytes_over_ceiling", + "capture_ai_max_event_bytes", + AI_MAX_MSG_SIZE + 1, + ), + ("event_bytes_zero", "capture_ai_max_event_bytes", 0), + ("event_bytes_float", "capture_ai_max_event_bytes", 1024.5), + ("event_bytes_bool", "capture_ai_max_event_bytes", True), + ("queue_size_negative", "capture_ai_max_queue_size", -1), + ("queue_size_string", "capture_ai_max_queue_size", "100"), + ("timeout_zero", "capture_ai_timeout", 0), + ("timeout_nan", "capture_ai_timeout", float("nan")), + ("timeout_inf", "capture_ai_timeout", float("inf")), + ("compression_unknown", "capture_ai_compression", "br"), + ] + ) + def test_invalid_ai_config_raises(self, _name, field, value): + with self.assertRaisesRegex(ValueError, field): + Client(TEST_API_KEY, send=False, **{field: value}) + + def test_async_lanes_keep_separate_path_and_compression(self): + client = Client(TEST_API_KEY, capture_compression="gzip", flush_interval=0.05) + with patch_capture_send("consumer") as mock_send: client.capture_ai("$ai_generation", distinct_id="d") client.capture("button_clicked", distinct_id="d") client.flush() - mock_v1.assert_called() + sends = { + call.kwargs["path"]: call.kwargs["compression"] + for call in mock_send.call_args_list + } self.assertEqual( - [call.kwargs["path"] for call in mock_post.call_args_list], - [AI_EVENTS_ENDPOINT], + sends, + { + _CAPTURE_AI_V1_PATH: CaptureCompression.NONE, + _CAPTURE_V1_PATH: CaptureCompression.GZIP, + }, + ) + self.assertEqual( + _events_by_path(mock_send)[_CAPTURE_AI_V1_PATH][0]["event"], + "$ai_generation", ) client.join() - def test_sync_ai_events_use_v0_even_with_capture_mode_v1(self): - client = Client(TEST_API_KEY, sync_mode=True, capture_mode="v1") - with ( - mock.patch("posthog.client.batch_post") as mock_post, - mock.patch("posthog.client._send_v1_batch") as mock_v1, - ): + def test_sync_lanes_keep_separate_path_compression_and_timeout(self): + client = Client( + TEST_API_KEY, + sync_mode=True, + capture_compression="gzip", + capture_ai_compression="deflate", + timeout=9, + capture_ai_timeout=45, + ) + with patch_capture_send("client") as mock_send: client.capture_ai("$ai_generation", distinct_id="d") client.capture("button_clicked", distinct_id="d") - mock_post.assert_called_once() - self.assertEqual(mock_post.call_args.kwargs["path"], AI_EVENTS_ENDPOINT) - mock_v1.assert_called_once() + self.assertEqual( + [ + ( + call.kwargs["path"], + call.kwargs["compression"], + call.kwargs["timeout"], + ) + for call in mock_send.call_args_list + ], + [ + (_CAPTURE_AI_V1_PATH, CaptureCompression.DEFLATE, 45), + (_CAPTURE_V1_PATH, CaptureCompression.GZIP, 9), + ], + ) + + def test_flush_drains_ai_lane_while_waiting_on_analytics(self): + release_analytics = threading.Event() + ai_sent = threading.Event() + + def send(api_key, host, batch, **kwargs): + if kwargs["path"] == _CAPTURE_AI_V1_PATH: + ai_sent.set() + else: + release_analytics.wait(5) + + client = Client(TEST_API_KEY, flush_interval=30) + with patch_capture_send("consumer", side_effect=send): + client.capture("button_clicked", distinct_id="d") + client.capture_ai("$ai_generation", distinct_id="d") + flusher = threading.Thread(target=client.flush, args=(10,)) + flusher.start() + try: + self.assertTrue(ai_sent.wait(2)) + finally: + release_analytics.set() + flusher.join(5) + client.join() class TestAiLaneLazyStart(unittest.TestCase): @@ -241,12 +393,12 @@ def test_no_ai_consumers_until_first_capture_ai(self): client = Client(TEST_API_KEY, flush_interval=0.05) self.assertEqual(client._ai_lane.consumers, []) - with mock.patch("posthog.consumer.batch_post"): + with patch_capture_send("consumer"): client.capture("button_clicked", distinct_id="d") client.flush() self.assertEqual(client._ai_lane.consumers, []) - with mock.patch("posthog.consumer.batch_post"): + with patch_capture_send("consumer"): client.capture_ai("$ai_generation", distinct_id="d") self.assertEqual(len(client._ai_lane.consumers), 1) self.assertTrue(client._ai_lane.consumers[0].is_alive()) @@ -262,7 +414,7 @@ def fire(): client.capture_ai("$ai_generation", distinct_id="d") threads = [threading.Thread(target=fire) for _ in range(8)] - with mock.patch("posthog.consumer.batch_post"): + with patch_capture_send("consumer"): for thread in threads: thread.start() for thread in threads: @@ -285,7 +437,7 @@ def test_fork_rebuild_restarts_analytics_and_resets_ai(self): client = Client( TEST_API_KEY, flush_interval=0.05, enable_local_evaluation=False ) - with mock.patch("posthog.consumer.batch_post"): + with patch_capture_send("consumer"): client.capture_ai("$ai_generation", distinct_id="d") client.flush() self.assertEqual(len(client._ai_lane.consumers), 1) @@ -305,14 +457,14 @@ def test_fork_rebuild_restarts_analytics_and_resets_ai(self): self.assertTrue(client._analytics_lane.consumers[0].is_alive()) self.assertEqual(client._ai_lane.consumers, []) - with mock.patch("posthog.consumer.batch_post") as mock_post: + with patch_capture_send("consumer") as mock_post: client.capture("button_clicked", distinct_id="d") client.capture_ai("$ai_generation", distinct_id="d") client.flush() self.assertEqual(len(client._ai_lane.consumers), 1) self.assertEqual( - set(_events_by_path(mock_post)), {EVENTS_ENDPOINT, AI_EVENTS_ENDPOINT} + set(_events_by_path(mock_post)), {_CAPTURE_V1_PATH, _CAPTURE_AI_V1_PATH} ) client.join() @@ -328,11 +480,14 @@ def test_fork_rebuild_replaces_sync_mode_queues(self): class TestCaptureAiEventHelper(unittest.TestCase): - """`_capture_ai_event` rides the AI lane only when the client opted in.""" + """`_capture_ai_event` always rides the AI lane; `enable_full_ai_capture` only controls content.""" - def test_opted_in_routes_through_ai_lane(self): - client = Client(TEST_API_KEY, flush_interval=0.05, enable_full_ai_capture=True) - with mock.patch("posthog.consumer.batch_post") as mock_post: + @parameterized.expand([("default", False), ("full_capture", True)]) + def test_routes_only_through_ai_lane(self, _name, full_capture): + client = Client( + TEST_API_KEY, flush_interval=0.05, enable_full_ai_capture=full_capture + ) + with patch_capture_send("consumer") as mock_post: _capture_ai_event( client, "$ai_generation", @@ -343,23 +498,10 @@ def test_opted_in_routes_through_ai_lane(self): self.assertEqual( [call.kwargs["path"] for call in mock_post.call_args_list], - [AI_EVENTS_ENDPOINT], + [_CAPTURE_AI_V1_PATH], ) client.join() - def test_default_keeps_capture_path(self): - client = Client(TEST_API_KEY, flush_interval=0.05) - with mock.patch("posthog.consumer.batch_post") as mock_post: - _capture_ai_event(client, "$ai_generation", distinct_id="d") - client.flush() - - self.assertEqual( - [call.kwargs["path"] for call in mock_post.call_args_list], - [EVENTS_ENDPOINT], - ) - self.assertEqual(client._ai_lane.consumers, []) - client.join() - def test_adds_ai_library_identity_and_preserves_provider_and_model(self): client = mock.Mock() _capture_ai_event( @@ -369,65 +511,117 @@ def test_adds_ai_library_identity_and_preserves_provider_and_model(self): properties={"$ai_provider": "openai", "$ai_model": "gpt-4o"}, ) - properties = client.capture.call_args.kwargs["properties"] + properties = client.capture_ai.call_args.kwargs["properties"] self.assertEqual(properties["$ai_lib"], "posthog-ai") self.assertEqual(properties["$ai_lib_version"], VERSION) self.assertEqual(properties["$ai_provider"], "openai") self.assertEqual(properties["$ai_model"], "gpt-4o") - def test_default_mock_clients_keep_seeing_capture(self): - # Downstream test suites pass Mock clients into the wrappers; without - # the opt-in they must keep seeing plain `capture()` calls. - client = mock.Mock() - _capture_ai_event(client, "$ai_generation", distinct_id="d") - client.capture.assert_called_once_with( - event="$ai_generation", - distinct_id="d", - properties={"$ai_lib": "posthog-ai", "$ai_lib_version": VERSION}, - ) - client.capture_ai.assert_not_called() - - def test_opted_in_prefers_capture_ai(self): - client = mock.Mock(spec=["capture", "capture_ai", "enable_full_ai_capture"]) - client.enable_full_ai_capture = True - _capture_ai_event(client, "$ai_generation", distinct_id="d") - client.capture_ai.assert_called_once_with( - event="$ai_generation", - distinct_id="d", - properties={"$ai_lib": "posthog-ai", "$ai_lib_version": VERSION}, - ) - client.capture.assert_not_called() - def test_opted_in_duck_typed_client_without_method_falls_back(self): - client = mock.Mock(spec=["capture", "enable_full_ai_capture"]) - client.enable_full_ai_capture = True - _capture_ai_event(client, "$ai_generation", distinct_id="d") - client.capture.assert_called_once_with( - event="$ai_generation", - distinct_id="d", - properties={"$ai_lib": "posthog-ai", "$ai_lib_version": VERSION}, - ) +_AZURE_KWARGS = { + "api_key": "test-key", + "azure_endpoint": "https://example.openai.azure.com", + "api_version": "2024-02-01", +} +_BEDROCK_KWARGS = { + "aws_region": "us-east-1", + "aws_access_key": "test-access-key", + "aws_secret_key": "test-secret-key", +} +_VERTEX_KWARGS = {"region": "us-east5", "project_id": "test", "access_token": "test"} - def test_client_multimodal_flag_prefers_capture_ai(self): - client = mock.Mock(spec=["capture", "capture_ai", "enable_full_ai_capture"]) - client.enable_full_ai_capture = True - _capture_ai_event(client, "$ai_generation", distinct_id="d") - client.capture_ai.assert_called_once_with( - event="$ai_generation", - distinct_id="d", - properties={"$ai_lib": "posthog-ai", "$ai_lib_version": VERSION}, - ) + +class TestAiIntegrationsRequireCaptureAi(unittest.TestCase): + @parameterized.expand( + [ + ("posthog.ai.openai", "OpenAI", "posthog_client", {"api_key": "test-key"}), + ( + "posthog.ai.openai", + "AsyncOpenAI", + "posthog_client", + {"api_key": "test-key"}, + ), + ("posthog.ai.openai", "AzureOpenAI", "posthog_client", _AZURE_KWARGS), + ("posthog.ai.openai", "AsyncAzureOpenAI", "posthog_client", _AZURE_KWARGS), + ( + "posthog.ai.anthropic", + "Anthropic", + "posthog_client", + {"api_key": "test-key"}, + ), + ( + "posthog.ai.anthropic", + "AsyncAnthropic", + "posthog_client", + {"api_key": "test-key"}, + ), + ( + "posthog.ai.anthropic", + "AnthropicBedrock", + "posthog_client", + _BEDROCK_KWARGS, + ), + ( + "posthog.ai.anthropic", + "AsyncAnthropicBedrock", + "posthog_client", + _BEDROCK_KWARGS, + ), + ( + "posthog.ai.anthropic", + "AnthropicVertex", + "posthog_client", + _VERTEX_KWARGS, + ), + ( + "posthog.ai.anthropic", + "AsyncAnthropicVertex", + "posthog_client", + _VERTEX_KWARGS, + ), + ("posthog.ai.gemini", "Client", "posthog_client", {"api_key": "test-key"}), + ( + "posthog.ai.gemini", + "AsyncClient", + "posthog_client", + {"api_key": "test-key"}, + ), + ("posthog.ai.langchain", "CallbackHandler", "client", {}), + ("posthog.ai.openai_agents", "PostHogTracingProcessor", "client", {}), + ( + "posthog.ai.claude_agent_sdk", + "PostHogClaudeAgentProcessor", + "client", + {}, + ), + ], + name_func=lambda func, _num, param: f"{func.__name__}_{param.args[1]}", + ) + def test_integration_logs_and_disables_capture_for_client_without_capture_ai( + self, module, integration, client_argument, kwargs + ): + integration_class = getattr(pytest.importorskip(module), integration) + client = mock.Mock(spec=["capture", "privacy_mode"]) + + with self.assertLogs("posthog", level="ERROR") as logs: + integration_class(**{client_argument: client}, **kwargs) + + self.assertEqual(len(logs.records), 1) + self.assertIn("capture_ai", logs.output[0]) client.capture.assert_not_called() - def test_client_multimodal_flag_off_keeps_capture(self): - client = mock.Mock(spec=["capture", "capture_ai", "enable_full_ai_capture"]) - client.enable_full_ai_capture = False - _capture_ai_event(client, "$ai_generation", distinct_id="d") - client.capture.assert_called_once_with( - event="$ai_generation", - distinct_id="d", - properties={"$ai_lib": "posthog-ai", "$ai_lib_version": VERSION}, + def test_disabled_ai_client_drops_ai_events_and_keeps_other_attributes(self): + client = mock.Mock(spec=["capture", "privacy_mode"]) + client.privacy_mode = True + + with self.assertLogs("posthog", level="ERROR"): + resolved = _resolve_ai_client(client) + + self.assertIsNone( + _capture_ai_event(resolved, "$ai_generation", distinct_id="d") ) + self.assertTrue(resolved.privacy_mode) + client.capture.assert_not_called() class TestLanesRefuseWorkAfterShutdown(unittest.TestCase): @@ -435,9 +629,9 @@ class TestLanesRefuseWorkAfterShutdown(unittest.TestCase): afterwards, even a lazy AI lane that never started before shutdown.""" def test_late_ai_capture_after_shutdown_starts_nothing_and_sends_nothing(self): - client = Client(TEST_API_KEY, enable_full_ai_capture=True, flush_interval=0.05) + client = Client(TEST_API_KEY, flush_interval=0.05) client.shutdown() - with mock.patch("posthog.consumer.batch_post") as mock_post: + with patch_capture_send("consumer") as mock_post: _capture_ai_event(client, "$ai_generation", distinct_id="d") client._ai_lane.queue.join() self.assertEqual(client._ai_lane.consumers, []) @@ -499,10 +693,10 @@ def _client(self, **kwargs): def test_new_flag_routes_wrapper_captures_to_ai_lane(self): client = self._client(enable_full_ai_capture=True) - with mock.patch("posthog.consumer.batch_post") as mock_post: + with patch_capture_send("consumer") as mock_post: _capture_ai_event(client, "$ai_generation", distinct_id="d") client.flush() - self.assertEqual(set(_events_by_path(mock_post)), {AI_EVENTS_ENDPOINT}) + self.assertEqual(set(_events_by_path(mock_post)), {_CAPTURE_AI_V1_PATH}) def test_deprecated_kwargs_map_to_new_flag(self): for kwargs in ({"_use_ai_lane": True}, {"_enable_multimodal_capture": True}): @@ -570,24 +764,24 @@ def _client(self, **kwargs): def test_returned_uuid_matches_the_wire_event_uuid(self): client = self._client() - with mock.patch("posthog.consumer.batch_post") as mock_post: + with patch_capture_send("consumer") as mock_post: returned_uuid = client.capture_ai("$ai_generation", distinct_id="d") client.flush() - batch = mock_post.call_args.kwargs["batch"] + batch = sent_batch(mock_post) self.assertEqual(batch[0]["uuid"], returned_uuid) def test_supplied_uuid_is_preserved_end_to_end(self): client = self._client() supplied_uuid = str(uuid.uuid4()) - with mock.patch("posthog.consumer.batch_post") as mock_post: + with patch_capture_send("consumer") as mock_post: returned_uuid = client.capture_ai( "$ai_generation", distinct_id="d", uuid=supplied_uuid ) client.flush() self.assertEqual(returned_uuid, supplied_uuid) - batch = mock_post.call_args.kwargs["batch"] + batch = sent_batch(mock_post) self.assertEqual(batch[0]["uuid"], supplied_uuid) def test_returned_uuid_reflects_before_send_replacement(self): @@ -598,12 +792,12 @@ def replace_uuid(event): return event client = self._client(before_send=replace_uuid) - with mock.patch("posthog.consumer.batch_post") as mock_post: + with patch_capture_send("consumer") as mock_post: returned_uuid = client.capture_ai("$ai_generation", distinct_id="d") client.flush() self.assertEqual(returned_uuid, replacement_uuid) - batch = mock_post.call_args.kwargs["batch"] + batch = sent_batch(mock_post) self.assertEqual(batch[0]["uuid"], replacement_uuid) def test_returned_uuid_is_regenerated_when_before_send_removes_it(self): @@ -612,26 +806,28 @@ def drop_uuid(event): return event client = self._client(before_send=drop_uuid) - with mock.patch("posthog.consumer.batch_post") as mock_post: + with patch_capture_send("consumer") as mock_post: returned_uuid = client.capture_ai("$ai_generation", distinct_id="d") client.flush() self.assertIsNotNone(returned_uuid) - batch = mock_post.call_args.kwargs["batch"] + batch = sent_batch(mock_post) self.assertEqual(batch[0]["uuid"], returned_uuid) class TestCaptureAiPrivacyMode(unittest.TestCase): """Privacy mode always wins over `enable_full_ai_capture`.""" - def test_privacy_mode_strips_content_despite_full_ai_capture(self): - client = Client( + @parameterized.expand([("sync", Client), ("async", AsyncPosthog)]) + def test_privacy_mode_strips_content_despite_full_ai_capture( + self, _name, client_cls + ): + client = client_cls( TEST_API_KEY, send=False, enable_full_ai_capture=True, privacy_mode=True, ) - self.addCleanup(client.join) payload = {"role": "user", "content": "sensitive prompt"} sanitized = with_privacy_mode( @@ -640,6 +836,33 @@ def test_privacy_mode_strips_content_despite_full_ai_capture(self): self.assertIsNone(sanitized) + @parameterized.expand( + [ + ("sync_default", Client, False), + ("sync_full_capture", Client, True), + ("async_default", AsyncPosthog, False), + ("async_full_capture", AsyncPosthog, True), + ] + ) + def test_full_ai_capture_controls_media_redaction( + self, _name, client_cls, full_capture + ): + client = client_cls( + TEST_API_KEY, send=False, enable_full_ai_capture=full_capture + ) + image = "data:image/jpeg;base64," + "A" * 64 + payload = [ + { + "role": "user", + "content": [{"type": "image_url", "image_url": {"url": image}}], + } + ] + + sanitized = finalize_ai_content(payload, ph_client=client) + + sent_url = sanitized[0]["content"][0]["image_url"]["url"] + self.assertEqual(sent_url == image, full_capture) + if __name__ == "__main__": unittest.main() diff --git a/posthog/test/test_async_client.py b/posthog/test/test_async_client.py index 97ea959fe..5f3cc79c4 100644 --- a/posthog/test/test_async_client.py +++ b/posthog/test/test_async_client.py @@ -3,22 +3,23 @@ import asyncio import contextvars import logging -from datetime import datetime, timezone -from pathlib import Path -from uuid import UUID import subprocess import sys import threading from unittest import mock +from uuid import UUID import pytest -from posthog import AsyncClient, AsyncPosthog, CaptureCompression, CaptureMode -from posthog.consumer import MAX_MSG_SIZE +from posthog import AsyncClient, AsyncPosthog, CaptureCompression +from posthog.capture_send import _CAPTURE_AI_V1_PATH, _CAPTURE_V1_PATH +from posthog.consumer import AI_MAX_MSG_SIZE, AI_MAX_PROPERTIES_SIZE, MAX_MSG_SIZE from posthog.contexts import ( identify_context, new_context, + set_context_option, set_context_session, + tag, set_capture_exception_code_variables_context, set_code_variables_detect_secrets_context, set_code_variables_ignore_patterns_context, @@ -26,6 +27,8 @@ set_code_variables_mask_url_credentials_context, ) from posthog.request import APIError +from posthog.test.capture_helpers import patch_async_capture_send +from posthog.test.logging_helpers import assert_before_send_failure_logged @pytest.mark.asyncio @@ -50,17 +53,17 @@ async def test_async_posthog_is_the_customer_facing_async_client(): async def test_capture_is_a_synchronous_queue_write_and_flushes(): batches = [] - async def batch_post(*args, **kwargs): - batches.append(kwargs["batch"]) + async def send_batch(api_key, host, batch, **kwargs): + batches.append(batch) - with mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post): + with patch_async_capture_send(side_effect=send_batch): async with AsyncPosthog("test-key", flush_at=100, flush_interval=30) as client: event_uuid = client.capture( "async event", distinct_id="user-1", properties={"plan": "pro"}, ) - assert isinstance(event_uuid, str) + assert UUID(event_uuid).version == 7 await client.flush(timeout_seconds=1) assert len(batches) == 1 @@ -74,6 +77,26 @@ async def batch_post(*args, **kwargs): assert event["uuid"] == event_uuid +@pytest.mark.asyncio +@pytest.mark.parametrize( + "supplied, warnings", + [("not-a-uuid-secret-1", 1), (123, 1), ("", 0), (None, 0)], +) +async def test_capture_replaces_unusable_uuid_and_warns_only_when_invalid( + caplog, supplied, warnings +): + client = AsyncPosthog("test-key", send=False) + with caplog.at_level(logging.WARNING, logger="posthog"): + event_uuid = client.capture("async event", distinct_id="user-1", uuid=supplied) + await client.shutdown() + + assert UUID(event_uuid).version == 7 + logged = [r for r in caplog.records if r.levelno >= logging.WARNING] + assert len(logged) == warnings + assert all(r.levelname == "WARNING" for r in logged) + assert all(str(supplied) not in r.getMessage() for r in logged) + + def test_capture_from_worker_thread_wakes_loop_bound_queue(): script = r""" import asyncio @@ -81,19 +104,18 @@ def test_capture_from_worker_thread_wakes_loop_bound_queue(): import threading from unittest import mock from posthog import AsyncPosthog +from posthog.test.capture_helpers import patch_async_capture_send async def main(): delivered = [] - async def batch_post(*args, **kwargs): - delivered.extend(kwargs["batch"]) + async def send_batch(api_key, host, batch, **kwargs): + delivered.extend(batch) - with mock.patch( - "posthog._async_consumer.async_batch_post", side_effect=batch_post - ): + with patch_async_capture_send(side_effect=send_batch): client = AsyncPosthog("test-key", flush_interval=30) - client._ensure_workers_started() - while not client._queue._getters: + client._ensure_workers_started(client._analytics_lane) + while not client._analytics_lane.queue._getters: await asyncio.sleep(0) asyncio.get_running_loop().set_debug(True) @@ -126,9 +148,12 @@ async def batch_post(*args, **kwargs): @pytest.mark.asyncio -async def test_cross_thread_capture_rechecks_shutdown_before_queue_admission(): +@pytest.mark.parametrize("method_name", ["capture", "capture_ai"]) +async def test_cross_thread_capture_rechecks_shutdown_before_queue_admission( + method_name, +): client = AsyncPosthog("test-key", flush_interval=30) - client._ensure_workers_started() + client._ensure_workers_started(client._analytics_lane) scheduled_callbacks = [] capture_result = [] @@ -139,7 +164,7 @@ async def test_cross_thread_capture_rechecks_shutdown_before_queue_admission(): ): capture_thread = threading.Thread( target=lambda: capture_result.append( - client.capture("threaded event", distinct_id="user-1") + getattr(client, method_name)("threaded event", distinct_id="user-1") ), daemon=True, ) @@ -152,9 +177,12 @@ async def test_cross_thread_capture_rechecks_shutdown_before_queue_admission(): capture_thread.join(timeout=1) assert capture_result == [None] - for task in client._worker_tasks: + assert client._ai_lane.worker_tasks == [] + assert client._pending_queue_items() == 0 + worker_tasks = client._all_worker_tasks() + for task in worker_tasks: task.cancel() - await asyncio.gather(*client._worker_tasks, return_exceptions=True) + await asyncio.gather(*worker_tasks, return_exceptions=True) await client._close_transport() @@ -167,10 +195,10 @@ async def before_send(event): event["properties"]["from_before_send"] = True return event - async def batch_post(*args, **kwargs): - batches.append(kwargs["batch"]) + async def send_batch(api_key, host, batch, **kwargs): + batches.append(batch) - with mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post): + with patch_async_capture_send(side_effect=send_batch): async with AsyncPosthog( "test-key", before_send=before_send, flush_interval=30 ) as client: @@ -181,6 +209,41 @@ async def batch_post(*args, **kwargs): assert batches[0][0]["uuid"] == event_uuid +@pytest.mark.asyncio +@pytest.mark.parametrize("bad_id", [123, 1.5, None, ["user"], {"id": "user"}]) +async def test_capture_drops_an_event_whose_before_send_distinct_id_is_not_a_string( + bad_id, +): + batches = [] + + def before_send(event): + if event["event"] == "bad": + event["distinct_id"] = bad_id + return event + + async def send_batch(api_key, host, batch, **kwargs): + batches.append(batch) + + with ( + patch_async_capture_send(side_effect=send_batch), + mock.patch("posthog.utils._warned_reasons", set()), + mock.patch.object(AsyncPosthog.log, "warning") as mock_warning, + ): + async with AsyncPosthog( + "test-key", before_send=before_send, flush_interval=30 + ) as client: + client.capture("bad", distinct_id="user") + client.capture("good", distinct_id="user") + assert await client.capture_immediate("bad", distinct_id="user") is None + await client.flush(timeout_seconds=1) + + events = [event for batch in batches for event in batch] + assert [(e["event"], e["distinct_id"]) for e in events] == [("good", "user")] + mock_warning.assert_called_once() + assert "distinct IDs must be strings" in mock_warning.call_args[0][0] + assert repr(bad_id) not in repr(mock_warning.call_args) + + @pytest.mark.asyncio async def test_capture_preserves_context_for_each_buffered_event(): request_id = contextvars.ContextVar("request_id") @@ -190,10 +253,10 @@ def before_send(event): event["properties"]["request_id"] = request_id.get() return event - async def batch_post(*args, **kwargs): - batches.append(kwargs["batch"]) + async def send_batch(api_key, host, batch, **kwargs): + batches.append(batch) - with mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post): + with patch_async_capture_send(side_effect=send_batch): client = AsyncPosthog("test-key", before_send=before_send, flush_interval=30) token = request_id.set("request-A") client.capture("event-A", distinct_id="user-1") @@ -222,7 +285,7 @@ def before_send(event): callback_thread = threading.get_ident() return event - with mock.patch("posthog._async_consumer.async_batch_post", new=mock.AsyncMock()): + with patch_async_capture_send(new=mock.AsyncMock()): client = AsyncPosthog("test-key", before_send=before_send) result = await client.capture_immediate("event", distinct_id="user-1") await client.shutdown() @@ -232,32 +295,48 @@ def before_send(event): @pytest.mark.asyncio -async def test_capture_drops_event_when_before_send_raises(): +async def test_capture_drops_event_when_before_send_raises(caplog): async def before_send(_event): raise RuntimeError("callback failed") - with mock.patch( - "posthog._async_consumer.async_batch_post", new=mock.AsyncMock() - ) as batch_post: + with patch_async_capture_send(new=mock.AsyncMock()) as send_batch: async with AsyncPosthog( "test-key", before_send=before_send, flush_interval=0.01 ) as client: - accepted_uuid = client.capture("event", distinct_id="user-1") - await client.flush(timeout_seconds=1) + with caplog.at_level(logging.DEBUG, logger="posthog"): + accepted_uuid = client.capture("event", distinct_id="user-1") + await client.flush(timeout_seconds=1) assert accepted_uuid is not None - batch_post.assert_not_awaited() + send_batch.assert_not_awaited() + assert_before_send_failure_logged(caplog.records, "event", "RuntimeError") + + +@pytest.mark.asyncio +async def test_capture_drops_event_when_before_send_returns_non_dict(caplog): + with patch_async_capture_send(new=mock.AsyncMock()) as send_batch: + async with AsyncPosthog( + "test-key", before_send=lambda _event: "invalid", flush_interval=0.01 + ) as client: + with caplog.at_level(logging.ERROR, logger="posthog"): + client.capture("event", distinct_id="user-1") + await client.flush(timeout_seconds=1) + + send_batch.assert_not_awaited() + assert [r.getMessage() for r in caplog.records] == [ + "[PostHog] before_send must return a dict or None, not str, dropping event event" + ] @pytest.mark.asyncio async def test_capture_immediate_waits_for_delivery(): delivered = asyncio.Event() - async def batch_post(*args, **kwargs): - assert kwargs["batch"][0]["event"] == "immediate event" + async def send_batch(api_key, host, batch, **kwargs): + assert batch[0]["event"] == "immediate event" delivered.set() - with mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post): + with patch_async_capture_send(side_effect=send_batch): client = AsyncPosthog("test-key") event_uuid = await client.capture_immediate( "immediate event", distinct_id="user-1" @@ -276,10 +355,10 @@ async def before_send(event): event["properties"]["processed"] = True return event - async def batch_post(*args, **kwargs): - batches.append(kwargs["batch"]) + async def send_batch(api_key, host, batch, **kwargs): + batches.append(batch) - with mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post): + with patch_async_capture_send(side_effect=send_batch): client = AsyncPosthog("test-key", before_send=before_send) result = await client.capture_immediate("event", distinct_id="user-1") await client.shutdown() @@ -289,24 +368,42 @@ async def batch_post(*args, **kwargs): @pytest.mark.asyncio -async def test_capture_immediate_drops_oversized_event_after_before_send(): +@pytest.mark.parametrize( + ("method_name", "client_kwargs", "payload_size", "sent"), + [ + ("capture_immediate", {}, MAX_MSG_SIZE, False), + ("capture_ai_immediate", {}, AI_MAX_PROPERTIES_SIZE, True), + ("capture_ai_immediate", {}, AI_MAX_MSG_SIZE, False), + ("capture_ai_immediate", {"capture_ai_max_event_bytes": 1024}, 2048, False), + ], +) +async def test_capture_immediate_applies_its_lane_size_cap_after_before_send( + method_name, client_kwargs, payload_size, sent +): def before_send(event): - event["properties"]["user_input"] = "x" * MAX_MSG_SIZE + event["properties"]["user_input"] = "x" * payload_size return event - with mock.patch( - "posthog._async_consumer.async_batch_post", new=mock.AsyncMock() - ) as batch_post: - client = AsyncPosthog("test-key", before_send=before_send) - result = await client.capture_immediate("event", distinct_id="user-1") + with patch_async_capture_send(new=mock.AsyncMock()) as send_batch: + client = AsyncPosthog("test-key", before_send=before_send, **client_kwargs) + result = await getattr(client, method_name)("event", distinct_id="user-1") await client.shutdown() - assert result is None - batch_post.assert_not_awaited() + assert (result is not None) is sent + assert send_batch.await_count == (1 if sent else 0) @pytest.mark.asyncio -async def test_capture_immediate_uses_capture_v1_without_building_httpx_client(): +@pytest.mark.parametrize( + ("method_name", "path", "compression", "timeout"), + [ + ("capture_immediate", _CAPTURE_V1_PATH, CaptureCompression.GZIP, 15), + ("capture_ai_immediate", _CAPTURE_AI_V1_PATH, CaptureCompression.DEFLATE, 45), + ], +) +async def test_capture_immediate_uses_its_lane_without_building_httpx_client( + method_name, path, compression, timeout +): with ( mock.patch( "posthog._async_consumer.async_send_v1_batch", new=mock.AsyncMock() @@ -315,33 +412,78 @@ async def test_capture_immediate_uses_capture_v1_without_building_httpx_client() ): client = AsyncPosthog( "test-key", - capture_mode=CaptureMode.V1, capture_compression=CaptureCompression.GZIP, + capture_ai_compression=CaptureCompression.DEFLATE, + capture_ai_timeout=45, + ) + event_uuid = await getattr(client, method_name)( + "$ai_generation", distinct_id="user-1" ) - event_uuid = await client.capture_immediate("event", distinct_id="user-1") await client.shutdown() assert event_uuid is not None build_client.assert_not_called() send_v1.assert_awaited_once() - assert send_v1.await_args.kwargs["compression"] == CaptureCompression.GZIP + assert send_v1.await_args.kwargs["path"] == path + assert send_v1.await_args.kwargs["compression"] == compression + assert send_v1.await_args.kwargs["timeout"] == timeout assert send_v1.await_args.args[2][0]["uuid"] == event_uuid @pytest.mark.asyncio -async def test_missing_async_extra_does_not_accept_undeliverable_events(): - with mock.patch( - "posthog.async_client._require_httpx", - side_effect=RuntimeError("install posthog[async]"), - ): - client = AsyncPosthog("test-key") - assert client.capture("event", distinct_id="user-1") is None - assert ( - client.set(distinct_id="user-1", properties={"email": "a@example.com"}) - is None +async def test_ai_events_queue_on_their_own_lane_and_flush_drains_both(): + sent: dict[str, list[str]] = {} + + async def send_batch(api_key, host, batch, **kwargs): + sent.setdefault(kwargs["path"], []).extend(e["event"] for e in batch) + + with patch_async_capture_send(side_effect=send_batch): + client = AsyncPosthog("test-key", flush_at=100, flush_interval=30) + client.capture("pageview", distinct_id="user-1") + assert client._ai_lane.worker_tasks == [] + client.capture_ai( + "$ai_generation", + distinct_id="user-1", + properties={"$ai_input": "x" * AI_MAX_PROPERTIES_SIZE}, ) - assert client._pending_queue_items() == 0 - assert client._worker_tasks == [] + await client.flush(timeout_seconds=1) + assert sent == { + _CAPTURE_V1_PATH: ["pageview"], + _CAPTURE_AI_V1_PATH: ["$ai_generation"], + } + + client.capture_ai("$ai_span", distinct_id="user-1") + await client.shutdown() + + assert sent[_CAPTURE_AI_V1_PATH] == ["$ai_generation", "$ai_span"] + assert client._all_worker_tasks() == [] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("event", [None, 123]) +async def test_ai_capture_handles_a_non_string_event_name_like_capture(event): + client = AsyncPosthog("test-key", send=False) + try: + expected = client.capture(event, distinct_id="user-1") is None + assert (client.capture_ai(event, distinct_id="user-1") is None) is expected + # The immediate paths process the event, so they drop the invalid name. + assert await client.capture_immediate(event, distinct_id="user-1") is None + assert await client.capture_ai_immediate(event, distinct_id="user-1") is None + finally: + await client.shutdown() + + +@pytest.mark.asyncio +@pytest.mark.parametrize("api_key", ["", " ", "phx_secret"]) +async def test_missing_or_personal_api_key_disables_the_client(api_key): + with mock.patch.object(AsyncPosthog.log, "error") as mock_error: + client = AsyncPosthog(api_key, send=False) + try: + assert client.disabled + assert client.capture("event", distinct_id="user-1") is None + mock_error.assert_called_once() + assert "secret" not in repr(mock_error.call_args) + finally: await client.shutdown() @@ -351,7 +493,7 @@ async def test_send_false_accepts_without_starting_workers_or_transport(): client = AsyncPosthog("test-key", send=False) assert client.capture("event", distinct_id="user-1") is not None assert await client.capture_immediate("event", distinct_id="user-1") is not None - assert client._worker_tasks == [] + assert client._all_worker_tasks() == [] await client.shutdown() build_client.assert_not_called() @@ -387,10 +529,10 @@ async def test_identify_methods_enqueue_events( ): batches = [] - async def batch_post(*args, **kwargs): - batches.append(kwargs["batch"]) + async def send_batch(api_key, host, batch, **kwargs): + batches.append(batch) - with mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post): + with patch_async_capture_send(side_effect=send_batch): async with AsyncPosthog("test-key", flush_interval=30) as client: method = getattr(client, method_name) assert method(**method_kwargs) is not None @@ -399,6 +541,50 @@ async def batch_post(*args, **kwargs): assert batches[0][0]["event"] == expected_event +@pytest.mark.asyncio +@pytest.mark.parametrize( + ("method_name", "method_kwargs", "expected_distinct_id", "expected_session"), + [ + ( + "group_identify", + {"group_type": "company", "group_key": "acme-1"}, + "context-user", + None, + ), + ( + "alias", + {"previous_id": "anon-1", "distinct_id": "user-1"}, + "anon-1", + "context-session", + ), + ], +) +async def test_identity_methods_take_context_values_by_the_context_rule( + method_name, method_kwargs, expected_distinct_id, expected_session +): + batches = [] + + async def send_batch(api_key, host, batch, **kwargs): + batches.append(batch) + + with patch_async_capture_send(side_effect=send_batch): + async with AsyncPosthog("test-key", flush_interval=30) as client: + with new_context(fresh=True): + identify_context("context-user") + set_context_session("context-session") + tag("tenant", "acme") + set_context_option("product_tour_id", "tour-1") + assert getattr(client, method_name)(**method_kwargs) is not None + assert client.alias("anon-2", None) is None + await client.flush(timeout_seconds=1) + + msg = batches[0][0] + assert msg["distinct_id"] == expected_distinct_id + assert msg["properties"].get("$session_id") == expected_session + assert msg["properties"]["tenant"] == "acme" + assert msg["options"]["product_tour_id"] == "tour-1" + + @pytest.mark.asyncio async def test_capture_after_shutdown_is_dropped_without_restarting_workers(): with mock.patch("posthog.async_client._build_client") as build_client: @@ -406,7 +592,7 @@ async def test_capture_after_shutdown_is_dropped_without_restarting_workers(): await client.shutdown() assert client.capture("event", distinct_id="user-1") is None assert await client.capture_immediate("event", distinct_id="user-1") is None - assert client._worker_tasks == [] + assert client._all_worker_tasks() == [] build_client.assert_not_called() @@ -414,12 +600,12 @@ async def test_capture_after_shutdown_is_dropped_without_restarting_workers(): async def test_batch_size_overflow_event_is_sent_in_the_next_batch(): batches = [] - async def batch_post(*args, **kwargs): - batches.append(kwargs["batch"]) + async def send_batch(api_key, host, batch, **kwargs): + batches.append(batch) with ( mock.patch("posthog._async_consumer.BATCH_SIZE_LIMIT", 800), - mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post), + patch_async_capture_send(side_effect=send_batch), ): client = AsyncPosthog("test-key", flush_at=10, flush_interval=30) client.capture("first", distinct_id="user-1", properties={"value": "a" * 400}) @@ -445,10 +631,10 @@ async def before_send(event): await allow_slow_callback.wait() return event - async def batch_post(*args, **kwargs): - delivered.extend(kwargs["batch"]) + async def send_batch(api_key, host, batch, **kwargs): + delivered.extend(batch) - with mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post): + with patch_async_capture_send(side_effect=send_batch): client = AsyncPosthog( "test-key", thread=2, @@ -474,12 +660,12 @@ async def test_shutdown_waits_for_an_in_flight_batch_instead_of_cancelling_it(): allow_upload = asyncio.Event() delivered = [] - async def batch_post(*args, **kwargs): + async def send_batch(api_key, host, batch, **kwargs): upload_started.set() await allow_upload.wait() - delivered.extend(kwargs["batch"]) + delivered.extend(batch) - with mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post): + with patch_async_capture_send(side_effect=send_batch): client = AsyncPosthog("test-key", flush_at=1) client.capture("event", distinct_id="user-1") await upload_started.wait() @@ -503,9 +689,7 @@ async def before_send(event): callback_finished.set() return event - with mock.patch( - "posthog._async_consumer.async_batch_post", new=mock.AsyncMock() - ) as batch_post: + with patch_async_capture_send(new=mock.AsyncMock()) as send_batch: client = AsyncPosthog("test-key", before_send=before_send, flush_at=1) client.capture("event", distinct_id="user-1") await asyncio.wait_for(callback_finished.wait(), timeout=1) @@ -516,7 +700,7 @@ async def wait_until_closed(): await asyncio.wait_for(wait_until_closed(), timeout=1) - batch_post.assert_awaited_once() + send_batch.assert_awaited_once() assert client.capture("after shutdown", distinct_id="user-1") is None @@ -531,10 +715,10 @@ async def before_send(event): await allow_callback.wait() return event - async def batch_post(*args, **kwargs): - delivered.extend(kwargs["batch"]) + async def send_batch(api_key, host, batch, **kwargs): + delivered.extend(batch) - with mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post): + with patch_async_capture_send(side_effect=send_batch): client = AsyncPosthog("test-key", before_send=before_send, flush_at=1) client.capture("event", distinct_id="user-1") await callback_started.wait() @@ -549,10 +733,10 @@ async def batch_post(*args, **kwargs): @pytest.mark.asyncio async def test_shutdown_returns_when_all_workers_exited_with_queued_work(): client = AsyncPosthog("test-key", flush_interval=30) - client._ensure_workers_started() - for task in client._worker_tasks: + client._ensure_workers_started(client._analytics_lane) + for task in client._analytics_lane.worker_tasks: task.cancel() - await asyncio.gather(*client._worker_tasks, return_exceptions=True) + await asyncio.gather(*client._analytics_lane.worker_tasks, return_exceptions=True) assert client.capture("undrainable event", distinct_id="user-1") is not None try: @@ -568,7 +752,7 @@ async def test_shutdown_waits_for_immediate_operation_not_its_long_lived_caller( allow_upload = asyncio.Event() shutdown_task = None - async def batch_post(*args, **kwargs): + async def send_batch(api_key, host, batch, **kwargs): upload_started.set() await allow_upload.wait() @@ -578,7 +762,7 @@ async def capture_then_await_shutdown(client): assert shutdown_task is not None await shutdown_task - with mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post): + with patch_async_capture_send(side_effect=send_batch): client = AsyncPosthog("test-key") caller = asyncio.create_task(capture_then_await_shutdown(client)) await upload_started.wait() @@ -592,11 +776,11 @@ async def test_shutdown_waits_for_in_flight_immediate_capture(): upload_started = asyncio.Event() allow_upload = asyncio.Event() - async def batch_post(*args, **kwargs): + async def send_batch(api_key, host, batch, **kwargs): upload_started.set() await allow_upload.wait() - with mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post): + with patch_async_capture_send(side_effect=send_batch): client = AsyncPosthog("test-key") capture = asyncio.create_task( client.capture_immediate("event", distinct_id="user-1") @@ -620,16 +804,17 @@ async def test_reuses_and_closes_instance_owned_http_client(): "posthog.async_client._build_client", return_value=http_client ) as build, mock.patch( - "posthog._async_consumer.async_batch_post", new=mock.AsyncMock() - ) as batch_post, + "posthog.async_client._async_flags", + new=mock.AsyncMock(return_value={"flags": {}}), + ) as flags, ): client = AsyncPosthog("test-key") - await client.capture_immediate("first", distinct_id="user-1") - await client.capture_immediate("second", distinct_id="user-1") + await client._get_flags_decision("user-1") + await client._get_flags_decision("user-2") await client.shutdown() build.assert_called_once_with(client.host) - assert [call.kwargs["client"] for call in batch_post.await_args_list] == [ + assert [call.kwargs["client"] for call in flags.await_args_list] == [ http_client, http_client, ] @@ -641,21 +826,28 @@ def test_capture_before_loop_starts_is_flushed_when_loop_runs(): client = AsyncPosthog("test-key", flush_interval=30) assert client.capture("event", distinct_id="user-1") is not None - async def batch_post(*args, **kwargs): - batches.append(kwargs["batch"]) + async def send_batch(api_key, host, batch, **kwargs): + batches.append(batch) async def flush_and_close(): - with mock.patch( - "posthog._async_consumer.async_batch_post", side_effect=batch_post - ): + with patch_async_capture_send(side_effect=send_batch): await client.shutdown() asyncio.run(flush_and_close()) assert batches[0][0]["event"] == "event" -@pytest.mark.parametrize(("option", "value"), [("flush_at", 0), ("flush_interval", 0)]) -def test_rejects_non_positive_batch_settings(option, value): +@pytest.mark.parametrize( + ("option", "value"), + [ + ("flush_at", 0), + ("flush_interval", 0), + ("capture_ai_max_queue_size", 0), + ("capture_ai_timeout", 0), + ("capture_ai_max_event_bytes", AI_MAX_MSG_SIZE + 1), + ], +) +def test_rejects_invalid_batch_settings(option, value): with pytest.raises(ValueError, match=option): AsyncPosthog("test-key", **{option: value}) @@ -668,6 +860,32 @@ async def test_capture_exception_never_raises_in_debug_mode(): await client.shutdown() +@pytest.mark.asyncio +@pytest.mark.parametrize( + ("level", "expected"), [(None, "error"), ("warning", "warning")] +) +async def test_capture_exception_sets_level_and_ignores_reserved_properties( + level, expected +): + client = AsyncPosthog("test-key", send=False) + with mock.patch.object(client, "capture", return_value="uuid") as capture: + client.capture_exception( + ValueError("boom"), + level=level, + properties={ + "$exception_list": [], + "$exception_level": "fatal", + "plan": "pro", + }, + ) + + properties = capture.call_args.kwargs["properties"] + assert properties["$exception_list"][0]["type"] == "ValueError" + assert properties["$exception_level"] == expected + assert properties["plan"] == "pro" + await client.shutdown() + + @pytest.mark.asyncio async def test_capture_exception_uses_context_code_variable_settings(): client = AsyncPosthog( @@ -704,7 +922,7 @@ async def test_capture_exception_uses_context_code_variable_settings(): @pytest.mark.asyncio async def test_queued_payload_is_not_written_to_debug_logs(caplog): caplog.set_level(logging.DEBUG, logger="posthog") - with mock.patch("posthog._async_consumer.async_batch_post", new=mock.AsyncMock()): + with patch_async_capture_send(new=mock.AsyncMock()): async with AsyncPosthog("test-key", flush_interval=30) as client: client.capture( "event", @@ -725,8 +943,7 @@ def on_error(error, batch): nonlocal callback_thread callback_thread = threading.get_ident() - with mock.patch( - "posthog._async_consumer.async_batch_post", + with patch_async_capture_send( side_effect=APIError(400, "failed"), ): client = AsyncPosthog("test-key", on_error=on_error, max_retries=0) @@ -739,14 +956,18 @@ def on_error(error, batch): @pytest.mark.asyncio @pytest.mark.parametrize("immediate", [False, True]) -async def test_failed_capture_does_not_log_server_response_detail(caplog, immediate): - caplog.set_level(logging.DEBUG, logger="posthog") - server_error = APIError(400, "password=server-secret") +async def test_capture_failure_inside_on_error_logs_instead_of_recursing( + caplog, immediate +): + calls = [] + client: AsyncPosthog - with mock.patch( - "posthog._async_consumer.async_batch_post", side_effect=server_error - ): - client = AsyncPosthog("test-key", flush_at=1, max_retries=0) + async def on_error(error, batch): + calls.append(batch[0]["event"]) + await client.capture_immediate("from_callback", distinct_id="user-1") + + with patch_async_capture_send(side_effect=APIError(503, "unavailable")): + client = AsyncPosthog("test-key", on_error=on_error, flush_at=1, max_retries=0) if immediate: await client.capture_immediate("event", distinct_id="user-1") else: @@ -754,9 +975,46 @@ async def test_failed_capture_does_not_log_server_response_detail(caplog, immedi await client.flush(timeout_seconds=1) await client.shutdown() + assert calls == ["event"] + assert ( + "1 event(s) not persisted by /i/v1/analytics/events: APIError (status=503)" + in caplog.text + ) + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + ("method_name", "path"), + [ + ("capture", _CAPTURE_V1_PATH), + ("capture_immediate", _CAPTURE_V1_PATH), + ("capture_ai", _CAPTURE_AI_V1_PATH), + ("capture_ai_immediate", _CAPTURE_AI_V1_PATH), + ], +) +async def test_failed_capture_logs_one_loss_line_without_response_detail( + caplog, method_name, path +): + caplog.set_level(logging.DEBUG, logger="posthog") + server_error = APIError(400, "password=server-secret") + + with patch_async_capture_send(side_effect=server_error): + client = AsyncPosthog("test-key", flush_at=1, max_retries=0) + result = getattr(client, method_name)("$ai_generation", distinct_id="user-1") + if method_name.endswith("_immediate"): + await result + await client.flush(timeout_seconds=1) + await client.shutdown() + assert "server-secret" not in caplog.text - assert "APIError" in caplog.text - assert "status=400" in caplog.text + loss_lines = [ + r.getMessage() + for r in caplog.records + if "event(s) not persisted by" in r.getMessage() + ] + assert loss_lines == [ + f"[PostHog] 1 event(s) not persisted by {path}: APIError (status=400)" + ] @pytest.mark.asyncio @@ -764,11 +1022,11 @@ async def test_flush_timeout_reports_unfinished_items(caplog): upload_started = asyncio.Event() allow_upload = asyncio.Event() - async def batch_post(*args, **kwargs): + async def send_batch(api_key, host, batch, **kwargs): upload_started.set() await allow_upload.wait() - with mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post): + with patch_async_capture_send(side_effect=send_batch): client = AsyncPosthog("test-key", flush_at=1) client.capture("event", distinct_id="user-1") await upload_started.wait() @@ -776,245 +1034,3 @@ async def batch_post(*args, **kwargs): assert "items pending" in caplog.text allow_upload.set() await client.shutdown() - - -@pytest.mark.asyncio -@pytest.mark.parametrize( - "method_name,method_kwargs,expected_id,expected_properties", - [ - ( - "group_identify", - { - "group_type": "company", - "group_key": "company-1", - "properties": {"plan": "pro", "nested": {"drop": None, "count": 0}}, - "distinct_id": "group-user", - }, - "group-user", - { - "$group_type": "company", - "$group_key": "company-1", - "$group_set": {"plan": "pro", "nested": {"drop": None, "count": 0}}, - }, - ), - ( - "alias", - {"previous_id": 123, "distinct_id": "alias-user"}, - "123", - {"distinct_id": "123", "alias": "alias-user"}, - ), - ], -) -async def test_identity_events_preserve_payload_session_and_normalized_envelope( - method_name, method_kwargs, expected_id, expected_properties -): - delivered = [] - - async def batch_post(*args, **kwargs): - delivered.extend(kwargs["batch"]) - - with mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post): - async with AsyncPosthog("test-key", flush_interval=30) as client: - with new_context(fresh=True): - set_context_session("request-session") - event_uuid = getattr(client, method_name)( - **method_kwargs, - uuid="{4BF92F35-77B3-4DA6-A3CE-929D0E0E4736}", - timestamp="2025-01-02T03:04:05.123456+02:30", - disable_geoip=False, - ) - await client.flush(timeout_seconds=1) - - assert len(delivered) == 1 - event = delivered[0] - assert event_uuid == event["uuid"] == "4bf92f35-77b3-4da6-a3ce-929d0e0e4736" - assert event["timestamp"] == "2025-01-02T00:34:05.123456+00:00" - assert event["distinct_id"] == expected_id - assert { - key: event["properties"][key] for key in expected_properties - } == expected_properties - assert event["properties"]["$session_id"] == "request-session" - assert "$geoip_disable" not in event["properties"] - - -@pytest.mark.asyncio -@pytest.mark.parametrize( - "method_name,method_kwargs", - [ - ("group_identify", {"group_type": "", "group_key": "company-1"}), - ("group_identify", {"group_type": "company", "group_key": ""}), - ("alias", {"previous_id": "", "distinct_id": "user-1"}), - ("alias", {"previous_id": "anon-1", "distinct_id": None}), - ], -) -async def test_identity_events_reject_missing_required_ids(method_name, method_kwargs): - with ( - new_context(fresh=True), - mock.patch( - "posthog._async_consumer.async_batch_post", new=mock.AsyncMock() - ) as send, - ): - async with AsyncPosthog("test-key") as client: - assert getattr(client, method_name)(**method_kwargs) is None - await client.flush() - send.assert_not_awaited() - - -@pytest.mark.asyncio -async def test_alias_uses_request_identity_when_no_explicit_distinct_id_is_supplied(): - delivered = [] - - async def batch_post(*args, **kwargs): - delivered.extend(kwargs["batch"]) - - with mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post): - async with AsyncPosthog("test-key") as client: - with new_context(fresh=True): - identify_context("request-user") - assert client.alias("anon-1", None) is not None - await client.flush() - - assert delivered[0]["distinct_id"] == "anon-1" - assert delivered[0]["properties"]["alias"] == "request-user" - - -@pytest.mark.asyncio -@pytest.mark.parametrize("cancel_immediate", [False, True]) -async def test_concurrent_shutdown_closes_once_after_immediate_operation_finishes( - cancel_immediate, -): - started, release = asyncio.Event(), asyncio.Event() - http_client = mock.Mock(aclose=mock.AsyncMock()) - on_error = mock.AsyncMock() - - async def batch_post(*args, **kwargs): - started.set() - await release.wait() - - with ( - mock.patch("posthog.async_client._build_client", return_value=http_client), - mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post), - ): - client = AsyncPosthog("test-key", on_error=on_error) - capture = asyncio.create_task(client.capture_immediate("in flight")) - await started.wait() - shutdowns = [asyncio.create_task(client.shutdown()) for _ in range(2)] - await asyncio.sleep(0) - assert client.capture("too late") is None - assert not any(task.done() for task in shutdowns) - http_client.aclose.assert_not_awaited() - if cancel_immediate: - capture.cancel() - with pytest.raises(asyncio.CancelledError): - await capture - else: - release.set() - assert await capture is not None - await asyncio.wait_for(asyncio.gather(*shutdowns), timeout=1) - - http_client.aclose.assert_awaited_once_with() - on_error.assert_not_awaited() - assert client._immediate_callers == {} - assert client._inflight_operations == set() - assert await client.capture_immediate("after shutdown") is None - - -@pytest.mark.asyncio -async def test_cancelled_shutdown_can_be_retried_without_cancelling_buffered_delivery(): - started, release = asyncio.Event(), asyncio.Event() - delivered = [] - - async def batch_post(*args, **kwargs): - started.set() - await release.wait() - delivered.extend(kwargs["batch"]) - - with mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post): - client = AsyncPosthog("test-key", flush_at=1) - event_uuid = client.capture("buffered") - await started.wait() - shutdown = asyncio.create_task(client.shutdown()) - await asyncio.sleep(0) - shutdown.cancel() - with pytest.raises(asyncio.CancelledError): - await shutdown - assert client.capture("after cancelled shutdown") is None - release.set() - await asyncio.wait_for(client.shutdown(), timeout=1) - - assert [event["uuid"] for event in delivered] == [event_uuid] - - -@pytest.mark.asyncio -@pytest.mark.parametrize("debug", [False, True]) -async def test_shutdown_attempts_remaining_cleanup_before_reporting_first_error(debug): - first_error = RuntimeError("flush failed") - http_client = mock.Mock( - aclose=mock.AsyncMock(side_effect=ValueError("close failed")) - ) - with ( - mock.patch("posthog.async_client._build_client", return_value=http_client), - mock.patch( - "posthog.async_client._async_flags", new=mock.AsyncMock(return_value={}) - ), - ): - client = AsyncPosthog("test-key", debug=debug, secret_key="secret-key") - await client.evaluate_flags("user-1") - emails = client.emails - with ( - mock.patch.object( - client, "flush", new=mock.AsyncMock(side_effect=first_error) - ), - mock.patch.object( - emails, - "aclose", - new=mock.AsyncMock(side_effect=OSError("email close failed")), - ) as close_email, - ): - if debug: - with pytest.raises(RuntimeError) as raised: - await client.shutdown() - assert raised.value is first_error - else: - await client.shutdown() - await client.shutdown() - - http_client.aclose.assert_awaited_once_with() - close_email.assert_awaited_once_with() - assert client._duplicate_client_registry_key is None - assert client._closed - assert client.capture("after shutdown") is None - - -@pytest.mark.asyncio -async def test_immediate_capture_replaces_invalid_uuid_and_timestamp_before_hook(): - observed = [] - - async def before_send(event): - observed.append(event.copy()) - return {**event, "uuid": "hook-cannot-replace-event-identity"} - - with mock.patch( - "posthog._async_consumer.async_batch_post", new=mock.AsyncMock() - ) as send: - client = AsyncPosthog("test-key", before_send=before_send) - before = datetime.now(timezone.utc) - event_uuid = await client.capture_immediate( - "event", uuid="invalid", timestamp="not-a-date" - ) - after = datetime.now(timezone.utc) - await client.shutdown() - - assert str(UUID(event_uuid)) == event_uuid - assert observed[0]["uuid"] == event_uuid - assert before <= datetime.fromisoformat(observed[0]["timestamp"]) <= after - assert send.await_args.kwargs["batch"][0]["uuid"] == event_uuid - - -@pytest.mark.asyncio -async def test_deprecated_secret_key_warning_points_to_constructor_caller(): - with pytest.warns(DeprecationWarning, match="personal_api_key") as warnings_seen: - client = AsyncPosthog("test-key", personal_api_key=" legacy-key ", send=False) - assert Path(warnings_seen[0].filename) == Path(__file__) - assert client.secret_key == client.personal_api_key == "legacy-key" - await client.shutdown() diff --git a/posthog/test/test_async_consumer.py b/posthog/test/test_async_consumer.py index 7ccae1efd..db3e17feb 100644 --- a/posthog/test/test_async_consumer.py +++ b/posthog/test/test_async_consumer.py @@ -1,18 +1,12 @@ from __future__ import annotations import asyncio -import contextvars -import json from unittest import mock -import httpx import pytest -from freezegun import freeze_time -from posthog._async_consumer import _AsyncConsumer, _QueuedEvent, _STOP +from posthog._async_consumer import _AsyncConsumer from posthog.capture_compression import CaptureCompression -from posthog.capture_mode import CaptureMode -from posthog.request import APIError def make_consumer(*, retries: int) -> _AsyncConsumer: @@ -21,140 +15,16 @@ def make_consumer(*, retries: int) -> _AsyncConsumer: "test-key", host="https://example.com", on_error=None, - process_event=mock.AsyncMock(side_effect=lambda event: event), + process_event=mock.AsyncMock(side_effect=lambda event, defaults: event), flush_at=100, flush_interval=1, - gzip=False, retries=retries, timeout=3, historical_migration=False, - capture_mode=CaptureMode.V0, capture_compression=CaptureCompression.NONE, - http_client=mock.Mock(), ) -@pytest.mark.asyncio -@pytest.mark.parametrize( - ("failures", "retry_after", "expected_delays"), - [ - (1, None, [1]), - (2, None, [1, 2]), - (2, 5, [5, 5]), - ], -) -async def test_request_retries_transient_failures_until_success( - failures, retry_after, expected_delays -): - error = APIError(503, "temporary", retry_after=retry_after) - consumer = make_consumer(retries=failures) - - with ( - mock.patch( - "posthog._async_consumer.async_batch_post", - new=mock.AsyncMock(side_effect=[error] * failures + [None]), - ) as batch_post, - mock.patch( - "posthog._async_consumer.asyncio.sleep", new=mock.AsyncMock() - ) as sleep, - ): - await consumer.request([{"event": "test"}]) - - assert batch_post.await_count == failures + 1 - assert [call.args[0] for call in sleep.await_args_list] == expected_delays - - -@pytest.mark.asyncio -@pytest.mark.parametrize( - ("retry_after", "expected_delay"), - [ - ("Tue, 08 Sep 2026 00:00:10 GMT", 10), - ("Tue, 08 Sep 2026 00:01:00 GMT", 30), - ("Mon, 07 Sep 2026 23:59:59 GMT", 1), - ("5", 5), - ("0", 1), - ("-1", 1), - ("invalid", 1), - (None, 1), - ], -) -async def test_request_honors_retry_after_from_http_response( - retry_after, expected_delay -): - headers = {"Retry-After": retry_after} if retry_after is not None else {} - responses = [ - httpx.Response(503, headers=headers, json={"detail": "temporary"}), - httpx.Response(200, json={"ok": True}), - ] - requests = [] - - def handle_request(request): - requests.append(request) - return responses.pop(0) - - consumer = make_consumer(retries=1) - batch = [{"event": "test", "distinct_id": "test-user"}] - async with httpx.AsyncClient( - base_url="https://example.com", transport=httpx.MockTransport(handle_request) - ) as client: - consumer.http_client = client - with ( - freeze_time("2026-09-08 00:00:00", real_asyncio=True), - mock.patch( - "posthog._async_consumer.asyncio.sleep", new=mock.AsyncMock() - ) as sleep, - ): - await consumer.request(batch) - - sleep.assert_awaited_once_with(expected_delay) - assert len(requests) == 2 - assert [json.loads(request.content)["batch"] for request in requests] == [ - batch, - batch, - ] - - -@pytest.mark.asyncio -@pytest.mark.parametrize("status", [400, 401, 413]) -async def test_request_does_not_retry_terminal_client_errors(status): - consumer = make_consumer(retries=3) - - with ( - mock.patch( - "posthog._async_consumer.async_batch_post", - new=mock.AsyncMock(side_effect=APIError(status, "terminal")), - ) as batch_post, - mock.patch( - "posthog._async_consumer.asyncio.sleep", new=mock.AsyncMock() - ) as sleep, - pytest.raises(APIError), - ): - await consumer.request([{"event": "test"}]) - - batch_post.assert_awaited_once() - sleep.assert_not_awaited() - - -@pytest.mark.asyncio -async def test_request_stops_after_configured_retry_limit(): - consumer = make_consumer(retries=2) - - with ( - mock.patch( - "posthog._async_consumer.async_batch_post", - new=mock.AsyncMock(side_effect=APIError(503, "temporary")), - ) as batch_post, - mock.patch( - "posthog._async_consumer.asyncio.sleep", new=mock.AsyncMock() - ) as sleep, - pytest.raises(APIError), - ): - await consumer.request([{"event": "test"}]) - - assert batch_post.await_count == 3 - assert [call.args[0] for call in sleep.await_args_list] == [1, 2] - - @pytest.mark.asyncio @pytest.mark.parametrize("run_worker", [False, True], ids=["wait", "worker"]) async def test_get_or_flush_cancels_waiters_on_cancellation(run_worker): @@ -208,113 +78,3 @@ async def test_get_or_flush_preserves_results_and_cleans_up_waiters(queued, flus assert not (asyncio.all_tasks() - tasks_before) if queued: consumer.queue.task_done() - - -@pytest.mark.asyncio -async def test_run_drops_invalid_events_and_preserves_queued_context(monkeypatch): - marker = contextvars.ContextVar("queued_test_marker", default="outside") - consumer = make_consumer(retries=0) - monkeypatch.setattr("posthog._async_consumer.MAX_MSG_SIZE", 256) - - async def process(event): - if event["event"] == "broken": - raise ValueError("processing failed") - if event["event"] == "filtered": - return None - return {**event, "context": marker.get()} - - consumer.process_event = process - token = marker.set("queued") - try: - for event in [ - {"event": "broken"}, - {"event": "filtered"}, - {"event": "invalid-json", "properties": {("tuple",): True}}, - {"event": "too-large", "properties": {"large": "x" * 256}}, - {"event": "accepted"}, - ]: - consumer.queue.put_nowait(_QueuedEvent(event, contextvars.copy_context())) - finally: - marker.reset(token) - consumer.queue.put_nowait(_STOP) - - with mock.patch( - "posthog._async_consumer.async_batch_post", new=mock.AsyncMock() - ) as batch_post: - await consumer.run() - await asyncio.wait_for(consumer.queue.join(), 1) - - assert batch_post.await_count == 1 - assert batch_post.await_args.kwargs["batch"] == [ - {"event": "accepted", "context": "queued"} - ] - assert marker.get() == "outside" - - -@pytest.mark.asyncio -async def test_next_carries_oversized_batch_tail_without_reprocessing(monkeypatch): - consumer = make_consumer(retries=0) - events = [{"event": "first"}, {"event": "second"}] - monkeypatch.setattr( - "posthog._async_consumer.BATCH_SIZE_LIMIT", - sum(len(json.dumps(event).encode()) for event in events) - 1, - ) - for event in events: - consumer.queue.put_nowait(_QueuedEvent(event, contextvars.copy_context())) - consumer.queue.put_nowait(_STOP) - - first, stopped_first = await consumer.next() - second, stopped_second = await consumer.next() - - assert first == [events[0]] - assert second == [events[1]] - assert (stopped_first, stopped_second) == (False, True) - assert consumer.process_event.await_count == 2 - with mock.patch.object(consumer, "request", new=mock.AsyncMock()): - await consumer.upload(first) - await consumer.upload(second) - await asyncio.wait_for(consumer.queue.join(), 1) - - -@pytest.mark.asyncio -async def test_upload_acknowledges_failed_batch_even_when_on_error_raises(): - consumer = make_consumer(retries=0) - consumer.on_error = mock.AsyncMock(side_effect=RuntimeError("callback failed")) - event = {"event": "failed"} - consumer.queue.put_nowait(event) - consumer.queue.get_nowait() - error = APIError(400, "terminal") - - with mock.patch( - "posthog._async_consumer.async_batch_post", - new=mock.AsyncMock(side_effect=error), - ): - await consumer.upload([event]) - await asyncio.wait_for(consumer.queue.join(), 1) - - consumer.on_error.assert_awaited_once_with(error, [event]) - - -@pytest.mark.asyncio -async def test_next_propagates_cancellation_during_event_processing(): - consumer = make_consumer(retries=0) - started = asyncio.Event() - cancelled = asyncio.Event() - - async def process(event): - started.set() - try: - await asyncio.Event().wait() - finally: - cancelled.set() - - consumer.process_event = process - consumer.queue.put_nowait( - _QueuedEvent({"event": "blocked"}, contextvars.copy_context()) - ) - task = asyncio.create_task(consumer.next()) - await asyncio.wait_for(started.wait(), 1) - task.cancel() - with pytest.raises(asyncio.CancelledError): - await task - assert cancelled.is_set() diff --git a/posthog/test/test_async_feature_flags.py b/posthog/test/test_async_feature_flags.py index 75c8b207e..b09387f60 100644 --- a/posthog/test/test_async_feature_flags.py +++ b/posthog/test/test_async_feature_flags.py @@ -8,9 +8,12 @@ import pytest from posthog import AsyncPosthog +from posthog.capture_event import _to_v1_event from posthog.client import _MINIMAL_FLAG_CALLED_EVENT_PROPERTIES from posthog.contexts import new_context, set_context_device_id from posthog.request import APIError +from posthog.test.capture_helpers import patch_async_capture_send +from posthog.version import VERSION def flags_response(*, minimal=False): @@ -138,15 +141,15 @@ async def test_empty_flag_keys_skips_remote_request(): async def test_snapshot_access_captures_one_flag_called_event_and_attaches_flags(): batches = [] - async def batch_post(*args, **kwargs): - batches.append(kwargs["batch"]) + async def send_batch(api_key, host, batch, **kwargs): + batches.append(batch) with ( mock.patch( "posthog.async_client._async_flags", new=mock.AsyncMock(return_value=flags_response()), ), - mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post), + patch_async_capture_send(side_effect=send_batch), ): client = AsyncPosthog("project-key", flush_interval=30) snapshot = await client.evaluate_flags("user-1") @@ -171,15 +174,15 @@ async def batch_post(*args, **kwargs): async def test_minimal_flag_called_event_uses_strict_property_allowlist(): batches = [] - async def batch_post(*args, **kwargs): - batches.append(kwargs["batch"]) + async def send_batch(api_key, host, batch, **kwargs): + batches.append(batch) with ( mock.patch( "posthog.async_client._async_flags", new=mock.AsyncMock(return_value=flags_response(minimal=True)), ), - mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post), + patch_async_capture_send(side_effect=send_batch), ): client = AsyncPosthog("project-key", flush_interval=30) snapshot = await client.evaluate_flags("user-1", flag_keys=["beta"]) @@ -200,6 +203,11 @@ async def batch_post(*args, **kwargs): "$feature_flag_request_id", "$feature_flag_has_experiment", } <= set(event["properties"]) + wire_properties = _to_v1_event(event)["properties"] + assert (wire_properties["$lib"], wire_properties["$lib_version"]) == ( + "posthog-python", + VERSION, + ) @pytest.mark.asyncio diff --git a/posthog/test/test_async_request.py b/posthog/test/test_async_request.py index 6b9e7b59a..876c5ca06 100644 --- a/posthog/test/test_async_request.py +++ b/posthog/test/test_async_request.py @@ -1,6 +1,5 @@ from __future__ import annotations -import asyncio import json import logging import subprocess @@ -14,7 +13,6 @@ from posthog._async_request import ( _build_client, _process_response, - async_batch_post, async_flags, async_remote_config, ) @@ -85,148 +83,6 @@ def test_build_client_scopes_requests_to_host_without_following_redirects(): ) -@pytest.mark.asyncio -async def test_async_batch_post_uses_configured_host_and_sanitized_logs(caplog): - caplog.set_level(logging.DEBUG, logger="posthog") - client = FakeAsyncClient() - - await async_batch_post( - "test-secret-key", - "https://example.com", - batch=[{"properties": {"password": "super-secret"}}], - path="/batch/", - client=client, - ) - - assert client.calls[0][1] == ("https://example.com/batch/",) - assert "super-secret" not in caplog.text - assert "test-secret-key" not in caplog.text - assert "https://example.com" not in caplog.text - - -@pytest.mark.asyncio -async def test_async_batch_post_follows_same_origin_temporary_redirect(): - client = FakeAsyncClient( - [ - FakeResponse(307, headers={"Location": "/redirected-batch/"}), - FakeResponse(200), - ] - ) - - await async_batch_post( - "test-key", - "https://example.com", - batch=[{"event": "event"}], - path="/batch/", - client=client, - ) - - assert [call[1] for call in client.calls] == [ - ("https://example.com/batch/",), - ("https://example.com/redirected-batch/",), - ] - - -@pytest.mark.asyncio -@pytest.mark.parametrize("status", [307, 308]) -@pytest.mark.parametrize( - "host", ["https://example.com/proxy", "https://example.com/proxy/"] -) -@pytest.mark.parametrize( - ("location", "redirected_path"), - [ - ("/proxy/redirected-batch/", "/proxy/redirected-batch/"), - ("https://example.com/proxy/redirected-batch/", "/proxy/redirected-batch/"), - ("/redirected-batch/", "/redirected-batch/"), - ("../redirected-batch/", "/proxy/redirected-batch/"), - ("?accepted=1", "/proxy/batch/?accepted=1"), - ], -) -async def test_async_batch_post_redirects_with_host_path_prefix( - status, host, location, redirected_path -): - requests = [] - responses = [ - httpx.Response(status, headers={"Location": location}), - httpx.Response(status, headers={"Location": "?attempt=2"}), - httpx.Response(200), - ] - - def handle_request(request): - requests.append(request) - return responses.pop(0) - - batch = [{"event": "test", "distinct_id": "test-user"}] - async with httpx.AsyncClient( - base_url=host, transport=httpx.MockTransport(handle_request) - ) as client: - await async_batch_post( - "test-key", host, batch=batch, path="/batch/", client=client - ) - - assert [str(request.url) for request in requests] == [ - "https://example.com/proxy/batch/", - f"https://example.com{redirected_path}", - f"https://example.com{redirected_path.split('?')[0]}?attempt=2", - ] - assert all(request.method == "POST" for request in requests) - assert all(request.content == requests[0].content for request in requests) - assert json.loads(requests[0].content)["batch"] == batch - - -@pytest.mark.asyncio -async def test_async_batch_post_rejects_cross_origin_temporary_redirect(): - client = FakeAsyncClient( - FakeResponse( - 307, - headers={"Location": "https://attacker.example/redirected-batch/"}, - ) - ) - - with pytest.raises(APIError): - await async_batch_post( - "test-key", - "https://example.com", - batch=[{"event": "event"}], - path="/batch/", - client=client, - ) - - assert len(client.calls) == 1 - - -@pytest.mark.asyncio -async def test_async_batch_post_serializes_off_event_loop(): - client = FakeAsyncClient() - real_to_thread = asyncio.to_thread - - with mock.patch( - "posthog._async_request.asyncio.to_thread", wraps=real_to_thread - ) as to_thread: - await async_batch_post( - "test-key", - "https://example.com", - batch=[{"event": "event"}], - path="/batch/", - gzip=True, - client=client, - ) - - to_thread.assert_awaited_once() - - -@pytest.mark.asyncio -async def test_async_batch_post_rejects_absolute_request_path(): - with pytest.raises(ValueError, match="relative"): - await async_batch_post( - "test-key", - "https://example.com", - batch=[], - path="https://attacker.example/batch/", - client=FakeAsyncClient(), - ) - - @pytest.mark.asyncio async def test_async_flags_sends_v2_request_payload(): client = FakeAsyncClient(FakeResponse(200, {"flags": {}})) diff --git a/posthog/test/test_before_send.py b/posthog/test/test_before_send.py index ee048290e..78e2e0d77 100644 --- a/posthog/test/test_before_send.py +++ b/posthog/test/test_before_send.py @@ -2,18 +2,30 @@ import unittest from unittest import mock +from parameterized import parameterized + import posthog from posthog.client import Client +from posthog.test.logging_helpers import assert_before_send_failure_logged from posthog.test.test_utils import FAKE_TEST_API_KEY +from posthog.test.capture_helpers import ( + patch_capture_send, + sent_batch, + sent_events, +) + + +_CIRCULAR: dict = {} +_CIRCULAR["self"] = _CIRCULAR class TestClient(unittest.TestCase): @classmethod def setUpClass(cls): # This ensures no real HTTP POST requests are made - cls.client_post_patcher = mock.patch("posthog.client.batch_post") - cls.consumer_post_patcher = mock.patch("posthog.consumer.batch_post") + cls.client_post_patcher = patch_capture_send("client") + cls.consumer_post_patcher = patch_capture_send("consumer") cls.client_post_patcher.start() cls.consumer_post_patcher.start() @@ -42,7 +54,7 @@ def my_before_send(event): event["properties"]["processed_by_before_send"] = True return event - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -57,7 +69,7 @@ def my_before_send(event): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) enqueued_msg = batch_data[0] self.assertEqual( @@ -75,7 +87,7 @@ def replace_uuid(event): event["uuid"] = replacement_uuid return event - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -87,7 +99,7 @@ def replace_uuid(event): self.assertEqual(msg_uuid, replacement_uuid) mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) enqueued_msg = batch_data[0] self.assertEqual(enqueued_msg["uuid"], replacement_uuid) @@ -98,7 +110,7 @@ def remove_uuid(event): del event["uuid"] return event - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -110,7 +122,7 @@ def remove_uuid(event): self.assertIsNotNone(msg_uuid) mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) enqueued_msg = batch_data[0] self.assertEqual(enqueued_msg["uuid"], msg_uuid) @@ -122,7 +134,7 @@ def drop_test_events(event): return None return event - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -140,7 +152,7 @@ def drop_test_events(event): # Check the enqueued message mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) enqueued_msg = batch_data[0] self.assertEqual(enqueued_msg["event"], "keep_me") @@ -152,7 +164,7 @@ def buggy_before_send(event): event["uuid"] = "invalid" raise ValueError("Oops!") - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -165,14 +177,16 @@ def buggy_before_send(event): "_normalize_event_uuid", wraps=client._normalize_event_uuid, ) as normalize_uuid, - self.assertLogs("posthog", level="ERROR") as logs, + self.assertLogs("posthog", level="DEBUG") as logs, ): msg_uuid = client.capture("robust_event", distinct_id="user1") self.assertIsNone(msg_uuid) mock_post.assert_not_called() normalize_uuid.assert_called_once() - self.assertIn("Error in before_send callback: Oops!", logs.output[0]) + assert_before_send_failure_logged( + logs.records, "robust_event", "ValueError" + ) def test_before_send_callback_exception_does_not_enqueue_mutated_event(self): def buggy_before_send(event): @@ -187,7 +201,7 @@ def buggy_before_send(event): ) try: with ( - mock.patch("posthog.consumer.batch_post") as mock_post, + patch_capture_send("consumer") as mock_post, mock.patch.object( client._analytics_lane, "enqueue", @@ -210,7 +224,7 @@ def add_unsupported_value(event): event["properties"]["marker"] = marker return event - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, before_send=add_unsupported_value, @@ -218,49 +232,69 @@ def add_unsupported_value(event): ) self.assertIsNotNone(client.capture("recleaned", distinct_id="user1")) - sent_event = mock_post.call_args.kwargs["batch"][0] + sent_event = sent_batch(mock_post)[0] self.assertIsNone(sent_event["properties"]["marker"]) def test_before_send_callback_non_dict_output_drops_event(self): - with ( - mock.patch("posthog.client.batch_post") as mock_post, - mock.patch("posthog.client.Client.log.exception") as mock_log, - ): + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, before_send=lambda _event: "invalid", sync_mode=True, ) - self.assertIsNone(client.capture("original", distinct_id="user1")) + with self.assertLogs("posthog", level="ERROR") as logs: + self.assertIsNone(client.capture("original", distinct_id="user1")) mock_post.assert_not_called() - self.assertIn( - "before_send must return a dict or None", mock_log.call_args.args[0] + self.assertEqual( + logs.output, + [ + "ERROR:posthog:[PostHog] before_send must return a dict or None, " + "not str, dropping event original" + ], ) - def test_malformed_before_send_event_does_not_stop_consumer_or_shutdown(self): - def add_invalid_mapping_key(event): + @parameterized.expand( + [ + # A key json cannot write costs only that key. + ( + "unwritable_key", + ("private-key",), + "private-value", + ["malformed", "valid"], + ), + # A circular value fails cleaning, so its event is dropped before it is queued. + ("circular_reference", "private-key", _CIRCULAR, ["valid"]), + # A value that survives cleaning but not json costs only its queued event. + ("unserializable_value", "private-key", complex(1, 2), ["valid"]), + ] + ) + def test_malformed_before_send_event_does_not_stop_consumer_or_shutdown( + self, _name, key, value, expected_events + ): + def add_malformed_property(event): if event["event"] == "malformed": - event["properties"][("private-key",)] = "private-value" + event["properties"][key] = value return event client = Client( FAKE_TEST_API_KEY, - before_send=add_invalid_mapping_key, - flush_at=1, + before_send=add_malformed_property, + flush_at=2, flush_interval=0.01, ) with ( - mock.patch("posthog.consumer.batch_post") as mock_post, - self.assertLogs("posthog", level="ERROR") as logs, + patch_capture_send("consumer") as mock_post, + self.assertLogs("posthog", level="DEBUG") as logs, ): client.capture("malformed", distinct_id="user1") client.capture("valid", distinct_id="user1") client.shutdown() mock_post.assert_called_once() - sent_batch = mock_post.call_args.kwargs["batch"] - self.assertEqual([event["event"] for event in sent_batch], ["valid"]) + sent = sent_batch(mock_post) + self.assertEqual([event["event"] for event in sent], expected_events) + self.assertTrue(all(key not in event["properties"] for event in sent)) self.assertEqual(client.queue.unfinished_tasks, 0) self.assertTrue(all(not consumer.is_alive() for consumer in client.consumers)) self.assertNotIn("private-key", "\n".join(logs.output)) @@ -275,7 +309,7 @@ def add_marker(event): event["properties"]["marked"] = True return event - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -293,14 +327,12 @@ def add_marker(event): # Check all events were marked self.assertEqual(mock_post.call_count, 2) - for call in mock_post.call_args_list: - batch_data = call[1]["batch"] - enqueued_msg = batch_data[0] - self.assertTrue(enqueued_msg["properties"]["marked"]) + for event in sent_events(mock_post): + self.assertTrue(event["properties"]["marked"]) def test_before_send_callback_disabled_when_none(self): """Test that client works normally when before_send is None.""" - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -312,7 +344,7 @@ def test_before_send_callback_disabled_when_none(self): # Check the event was sent normally mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) enqueued_msg = batch_data[0] self.assertEqual(enqueued_msg["event"], "normal_event") @@ -336,7 +368,7 @@ def scrub_pii(event): return event - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -357,7 +389,7 @@ def scrub_pii(event): # Check the enqueued message was scrubbed mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) enqueued_msg = batch_data[0] self.assertEqual(enqueued_msg["properties"]["email"], "***@example.com") @@ -379,7 +411,7 @@ def my_before_send(event): event["properties"]["module_level_before_send"] = True return event - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: posthog.api_key = FAKE_TEST_API_KEY posthog.before_send = my_before_send posthog.sync_mode = True @@ -390,7 +422,7 @@ def my_before_send(event): self.assertIs(posthog.default_client.before_send, my_before_send) mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) enqueued_msg = batch_data[0] self.assertTrue(enqueued_msg["properties"]["module_level_before_send"]) @@ -399,7 +431,7 @@ def my_before_send(event): event["properties"]["updated_after_init"] = True return event - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: posthog.api_key = FAKE_TEST_API_KEY posthog.sync_mode = True @@ -413,8 +445,8 @@ def my_before_send(event): self.assertIs(posthog.default_client.before_send, my_before_send) self.assertEqual(mock_post.call_count, 2) - first_batch = mock_post.call_args_list[0][1]["batch"] - second_batch = mock_post.call_args_list[1][1]["batch"] + first_batch = sent_batch(mock_post, 0) + second_batch = sent_batch(mock_post, 1) self.assertNotIn("updated_after_init", first_batch[0]["properties"]) self.assertTrue(second_batch[0]["properties"]["updated_after_init"]) diff --git a/posthog/test/test_capture_compression.py b/posthog/test/test_capture_compression.py index a4ce0154f..cb9376572 100644 --- a/posthog/test/test_capture_compression.py +++ b/posthog/test/test_capture_compression.py @@ -22,15 +22,9 @@ def setUp(self) -> None: self.addCleanup(patcher.stop) os.environ.pop(CAPTURE_COMPRESSION_ENV_VAR, None) - def test_defaults_to_none_with_no_kwarg_env_or_gzip(self) -> None: + def test_defaults_to_none_with_no_kwarg_or_env(self) -> None: self.assertIs(_resolve_capture_compression(None), CaptureCompression.NONE) - def test_gzip_fallback_used_when_nothing_else_set(self) -> None: - self.assertIs( - _resolve_capture_compression(None, gzip_fallback=True), - CaptureCompression.GZIP, - ) - @parameterized.expand( [ ("enum_gzip", CaptureCompression.GZIP, CaptureCompression.GZIP), @@ -48,12 +42,9 @@ def test_gzip_fallback_used_when_nothing_else_set(self) -> None: def test_explicit_kwarg_takes_precedence_and_coerces( self, _name, kwarg, expected ) -> None: - # Env names a different value and gzip_fallback is on, so each row proves - # the explicit kwarg wins over both lower-precedence sources. + # Env names a different value, so each row proves the explicit kwarg wins. with mock.patch.dict(os.environ, {CAPTURE_COMPRESSION_ENV_VAR: "deflate"}): - self.assertIs( - _resolve_capture_compression(kwarg, gzip_fallback=True), expected - ) + self.assertIs(_resolve_capture_compression(kwarg), expected) def test_invalid_kwarg_raises_even_with_valid_env(self) -> None: with mock.patch.dict(os.environ, {CAPTURE_COMPRESSION_ENV_VAR: "gzip"}): @@ -80,28 +71,16 @@ def test_env_var_resolution(self, _name, env_value, expected) -> None: with mock.patch.dict(os.environ, {CAPTURE_COMPRESSION_ENV_VAR: env_value}): self.assertIs(_resolve_capture_compression(None), expected) - def test_env_var_takes_precedence_over_gzip_fallback(self) -> None: - with mock.patch.dict(os.environ, {CAPTURE_COMPRESSION_ENV_VAR: "deflate"}): - self.assertIs( - _resolve_capture_compression(None, gzip_fallback=True), - CaptureCompression.DEFLATE, - ) - @parameterized.expand([("empty", ""), ("whitespace", " ")]) - def test_blank_env_var_falls_through_to_fallback(self, _name, env_value) -> None: + def test_blank_env_var_falls_through_to_none(self, _name, env_value) -> None: with mock.patch.dict(os.environ, {CAPTURE_COMPRESSION_ENV_VAR: env_value}): self.assertIs(_resolve_capture_compression(None), CaptureCompression.NONE) - self.assertIs( - _resolve_capture_compression(None, gzip_fallback=True), - CaptureCompression.GZIP, - ) - def test_unrecognized_env_var_warns_and_uses_fallback(self) -> None: + def test_unrecognized_env_var_warns_and_uses_none(self) -> None: with mock.patch.dict(os.environ, {CAPTURE_COMPRESSION_ENV_VAR: "bogus"}): with capture_message_only_logs() as stream: self.assertIs( - _resolve_capture_compression(None, gzip_fallback=True), - CaptureCompression.GZIP, + _resolve_capture_compression(None), CaptureCompression.NONE ) self.assertIn("bogus", stream.getvalue()) @@ -112,13 +91,12 @@ def test_explicit_zstd_without_package_raises(self, _name, kwarg) -> None: _resolve_capture_compression(kwarg) self.assertIn("posthog[zstd]", str(ctx.exception)) - def test_env_zstd_without_package_warns_and_uses_fallback(self) -> None: + def test_env_zstd_without_package_warns_and_uses_none(self) -> None: with mock.patch("posthog.capture_compression._zstandard", None): with mock.patch.dict(os.environ, {CAPTURE_COMPRESSION_ENV_VAR: "zstd"}): with capture_message_only_logs() as stream: self.assertIs( - _resolve_capture_compression(None, gzip_fallback=True), - CaptureCompression.GZIP, + _resolve_capture_compression(None), CaptureCompression.NONE ) self.assertIn("posthog[zstd]", stream.getvalue()) @@ -134,10 +112,6 @@ def test_client_defaults_to_none(self) -> None: client = Client(TEST_API_KEY, sync_mode=True) self.assertIs(client.capture_compression, CaptureCompression.NONE) - def test_client_gzip_flag_falls_back_to_gzip(self) -> None: - client = Client(TEST_API_KEY, sync_mode=True, gzip=True) - self.assertIs(client.capture_compression, CaptureCompression.GZIP) - @parameterized.expand( [ ("enum_deflate", CaptureCompression.DEFLATE, CaptureCompression.DEFLATE), @@ -145,11 +119,8 @@ def test_client_gzip_flag_falls_back_to_gzip(self) -> None: ("str_none", "none", CaptureCompression.NONE), ] ) - def test_client_kwarg_overrides_gzip_flag(self, _name, kwarg, expected) -> None: - # Even with the legacy gzip flag on, the explicit kwarg wins. - client = Client( - TEST_API_KEY, sync_mode=True, gzip=True, capture_compression=kwarg - ) + def test_client_kwarg_sets_compression(self, _name, kwarg, expected) -> None: + client = Client(TEST_API_KEY, sync_mode=True, capture_compression=kwarg) self.assertIs(client.capture_compression, expected) def test_client_propagates_to_consumers(self) -> None: diff --git a/posthog/test/test_capture_event.py b/posthog/test/test_capture_event.py new file mode 100644 index 000000000..9c50e57e2 --- /dev/null +++ b/posthog/test/test_capture_event.py @@ -0,0 +1,313 @@ +import unittest +from datetime import datetime, timedelta, timezone +from unittest import mock + +from parameterized import parameterized + +from uuid import UUID + +from posthog.capture_event import ( + _build_v1_batch_body, + _canonical_event_uuid, + _to_v1_event, +) + + +def _legacy_msg(event="my_event", properties=None, **overrides) -> dict: + """Minimal legacy-shaped message as it looks coming off the queue.""" + msg = { + "event": event, + "uuid": "0190000000007000800000000000000a", + "distinct_id": "user-1", + "timestamp": "2026-06-27T12:00:00+00:00", + "type": "capture", + "properties": {"$lib": "posthog-python", "$lib_version": "9.9.9"}, + } + if properties is not None: + msg["properties"] = properties + msg.update(overrides) + return msg + + +_CANONICAL_UUID = "0190a8f3-1b2c-7d4e-8f90-123456789abc" + + +class TestCanonicalEventUuid(unittest.TestCase): + @parameterized.expand( + [ + ("canonical", _CANONICAL_UUID), + ("uppercase", _CANONICAL_UUID.upper()), + ("unhyphenated", _CANONICAL_UUID.replace("-", "")), + ("braced", "{" + _CANONICAL_UUID + "}"), + ("urn", "urn:uuid:" + _CANONICAL_UUID), + ("urn_uppercase", "URN:UUID:" + _CANONICAL_UUID.upper()), + ("uuid_instance", UUID(_CANONICAL_UUID)), + ] + ) + def test_accepted_forms_are_canonicalized(self, _name, value) -> None: + self.assertEqual(_canonical_event_uuid(value), _CANONICAL_UUID) + + @parameterized.expand( + [ + ("bare_uuid_prefix", "uuid:" + _CANONICAL_UUID), + ("misplaced_hyphen", "0190a8f31-b2c-7d4e-8f90-123456789abc"), + ("surrounding_whitespace", " " + _CANONICAL_UUID), + ("braced_unhyphenated", "{" + _CANONICAL_UUID.replace("-", "") + "}"), + ("too_short", _CANONICAL_UUID[:-1]), + ("empty", ""), + ("int", 123), + ] + ) + def test_other_forms_are_rejected(self, _name, value) -> None: + self.assertIsNone(_canonical_event_uuid(value)) + + +def _whole_second_clock() -> "mock._patch": + whole_second = datetime(2026, 6, 27, 12, tzinfo=timezone.utc) + return mock.patch( + "posthog.capture_event.datetime", + wraps=datetime, + **{"now.return_value": whole_second}, + ) + + +class TestToV1Event(unittest.TestCase): + def test_required_fields_preserved(self) -> None: + event = _to_v1_event(_legacy_msg(event="signed_up")) + self.assertEqual(event["event"], "signed_up") + self.assertEqual(event["uuid"], "0190000000007000800000000000000a") + self.assertEqual(event["distinct_id"], "user-1") + self.assertEqual(event["timestamp"], "2026-06-27T12:00:00.000000+00:00") + + @parameterized.expand( + [ + ("sdk", {"$lib": "posthog-python", "$lib_version": "9.9.9"}), + ("caller_lib_alone", {"$lib": "caller-lib"}), + ("null", {"$lib": None, "$lib_version": None}), + ] + ) + def test_sends_lib_and_lib_version_as_given(self, _name, library) -> None: + event = _to_v1_event(_legacy_msg(properties=dict(library))) + self.assertEqual(event["properties"], library) + + def test_options_empty_dict_when_no_sentinels(self) -> None: + event = _to_v1_event(_legacy_msg(properties={"plain": "value"})) + self.assertEqual(event["options"], {}) + self.assertEqual(event["properties"], {"plain": "value"}) + + def test_does_not_leak_non_wire_top_level_keys(self) -> None: + event = _to_v1_event(_legacy_msg()) + # `type` is legacy-only; the v1 event carries only documented fields. + self.assertEqual( + set(event), + {"event", "uuid", "distinct_id", "timestamp", "options", "properties"}, + ) + + def test_does_not_mutate_input(self) -> None: + msg = _legacy_msg( + properties={"$cookieless_mode": True, "$session_id": "s-1"}, + options={"product_tour_id": "tour-1"}, + **{"$set": {"name": "Max"}}, + ) + original_properties = dict(msg["properties"]) + _to_v1_event(msg) + self.assertEqual(msg["properties"], original_properties) + self.assertEqual(msg["options"], {"product_tour_id": "tour-1"}) + self.assertIn("$set", msg) # top-level $set untouched on the original + + @parameterized.expand( + [ + ("cookieless_mode", "$cookieless_mode", "cookieless_mode", True), + ("ignore_sent_at", "$ignore_sent_at", "disable_skew_correction", "true"), + ( + "process_person_profile", + "$process_person_profile", + "process_person_profile", + 0, + ), + ("product_tour_id", "$product_tour_id", "product_tour_id", 123), + ] + ) + def test_legacy_property_fills_option_unchanged( + self, _name, prop_key, option_key, raw + ) -> None: + event = _to_v1_event(_legacy_msg(properties={prop_key: raw})) + self.assertEqual(event["options"], {option_key: raw}) + self.assertNotIn(prop_key, event["properties"]) + + @parameterized.expand( + [ + ("option_set", {"cookieless_mode": False}, False), + ("option_null", {"cookieless_mode": None}, True), + ("option_missing", {}, True), + ] + ) + def test_caller_option_wins_over_legacy_property( + self, _name, options, expected + ) -> None: + event = _to_v1_event( + _legacy_msg(properties={"$cookieless_mode": True}, options=options) + ) + self.assertEqual(event["options"], {"cookieless_mode": expected}) + self.assertNotIn("$cookieless_mode", event["properties"]) + + def test_caller_options_pass_through_unchanged(self) -> None: + options = {"process_person_profile": "false", "future_option": {"a": [1]}} + event = _to_v1_event(_legacy_msg(options=options)) + self.assertEqual(event["options"], options) + + @parameterized.expand([("list", ["x"]), ("string", "x"), ("int", 1)]) + def test_non_dict_options_are_logged_and_ignored(self, _name, options) -> None: + with self.assertLogs("posthog", level="ERROR") as logs: + event = _to_v1_event( + _legacy_msg(properties={"$cookieless_mode": True}, options=options) + ) + self.assertEqual(event["options"], {"cookieless_mode": True}) + self.assertIn("options must be a dict", logs.output[0]) + + @parameterized.expand( + [ + ("session_id", "$session_id", "session_id", "s-123"), + ("window_id", "$window_id", "window_id", "w-456"), + ("empty_string", "$session_id", "session_id", ""), + ] + ) + def test_top_level_string_sentinels(self, _name, prop_key, field_name, raw) -> None: + event = _to_v1_event(_legacy_msg(properties={prop_key: raw})) + self.assertEqual(event[field_name], raw) + self.assertNotIn(prop_key, event["properties"]) + + @parameterized.expand( + [ + ("number", "$session_id", 42, "number"), + ("bool", "$window_id", True, "bool"), + ("array", "$session_id", ["s-1"], "array"), + ("object", "$window_id", {"id": "w-1"}, "object"), + ] + ) + def test_non_string_sentinel_is_dropped_with_a_warning( + self, _name, prop_key, raw, type_name + ) -> None: + with self.assertLogs("posthog", level="WARNING") as logs: + event = _to_v1_event(_legacy_msg(properties={prop_key: raw})) + self.assertNotIn(prop_key.lstrip("$"), event) + self.assertNotIn(prop_key, event["properties"]) + self.assertIn( + f"dropping {prop_key}: a {type_name} value is not a string", + logs.records[0].getMessage(), + ) + + def test_null_sentinel_is_dropped_silently(self) -> None: + with self.assertNoLogs("posthog", level="WARNING"): + event = _to_v1_event(_legacy_msg(properties={"$session_id": None})) + self.assertNotIn("session_id", event) + self.assertNotIn("$session_id", event["properties"]) + + def test_all_sentinels_together(self) -> None: + event = _to_v1_event( + _legacy_msg( + properties={ + "$cookieless_mode": True, + "$ignore_sent_at": True, + "$product_tour_id": "tour-x", + "$process_person_profile": False, + "$session_id": "s-1", + "$window_id": "w-1", + "$geoip_disable": True, + "custom": "keep", + } + ) + ) + self.assertEqual( + event["options"], + { + "cookieless_mode": True, + "disable_skew_correction": True, + "product_tour_id": "tour-x", + "process_person_profile": False, + }, + ) + self.assertEqual(event["session_id"], "s-1") + self.assertEqual(event["window_id"], "w-1") + # Non-sentinel props (including $geoip_disable) are left intact. + self.assertEqual( + event["properties"], {"$geoip_disable": True, "custom": "keep"} + ) + + @parameterized.expand([("set", "$set"), ("set_once", "$set_once")]) + def test_top_level_set_relocated_into_properties(self, _name, key) -> None: + msg = _legacy_msg(properties={}, **{key: {"email": "a@b.com"}}) + event = _to_v1_event(msg) + self.assertEqual(event["properties"][key], {"email": "a@b.com"}) + self.assertNotIn(key, event) # not a top-level v1 field + + def test_top_level_set_merges_with_existing_properties_set(self) -> None: + msg = _legacy_msg( + properties={"$set": {"a": "from_props", "b": "props_only"}}, + **{"$set": {"a": "from_top", "c": "top_only"}}, + ) + event = _to_v1_event(msg) + self.assertEqual( + event["properties"]["$set"], + {"a": "from_top", "b": "props_only", "c": "top_only"}, + ) + + def test_groups_left_in_properties(self) -> None: + event = _to_v1_event(_legacy_msg(properties={"$groups": {"company": "ph"}})) + self.assertEqual(event["properties"]["$groups"], {"company": "ph"}) + + def test_timestamp_naive_datetime_made_tz_aware(self) -> None: + event = _to_v1_event(_legacy_msg(timestamp=datetime(2026, 6, 27, 12, 0, 0))) + parsed = datetime.fromisoformat(event["timestamp"]) + self.assertIsNotNone(parsed.tzinfo) + + def test_timestamp_aware_datetime_converted_to_exact_utc_instant(self) -> None: + event = _to_v1_event( + _legacy_msg( + timestamp=datetime( + 2026, + 6, + 27, + 17, + 45, + tzinfo=timezone(timedelta(hours=5, minutes=45)), + ) + ) + ) + self.assertEqual(event["timestamp"], "2026-06-27T12:00:00.000000+00:00") + + def test_timestamp_parseable_string_converted_to_exact_utc_instant(self) -> None: + event = _to_v1_event(_legacy_msg(timestamp="2026-06-27T17:45:00+05:45")) + self.assertEqual(event["timestamp"], "2026-06-27T12:00:00.000000+00:00") + + def test_timestamp_none_defaults_to_utc_now(self) -> None: + with _whole_second_clock(): + event = _to_v1_event(_legacy_msg(timestamp=None)) + self.assertEqual(event["timestamp"], "2026-06-27T12:00:00.000000+00:00") + + +class TestBuildV1BatchBody(unittest.TestCase): + def test_envelope_shape_and_no_legacy_fields(self) -> None: + events = [{"event": "e"}] + body = _build_v1_batch_body(events) + self.assertEqual(body["batch"], events) + self.assertNotIn("api_key", body) + self.assertNotIn("sent_at", body) + + def test_created_at_defaults_to_utc_now(self) -> None: + with _whole_second_clock(): + body = _build_v1_batch_body([]) + self.assertEqual(body["created_at"], "2026-06-27T12:00:00.000000+00:00") + + def test_created_at_passthrough_used_verbatim(self) -> None: + # _send_v1_batch hoists created_at and passes it in so it stays stable + # across retry attempts. + body = _build_v1_batch_body([], created_at="2026-06-27T12:00:00+00:00") + self.assertEqual(body["created_at"], "2026-06-27T12:00:00+00:00") + + def test_historical_migration_omitted_when_false(self) -> None: + self.assertNotIn("historical_migration", _build_v1_batch_body([])) + + def test_historical_migration_present_when_true(self) -> None: + body = _build_v1_batch_body([], historical_migration=True) + self.assertIs(body["historical_migration"], True) diff --git a/posthog/test/test_capture_invariants.py b/posthog/test/test_capture_invariants.py new file mode 100644 index 000000000..bf7f2c7bb --- /dev/null +++ b/posthog/test/test_capture_invariants.py @@ -0,0 +1,204 @@ +import asyncio +import json +from contextlib import ExitStack, contextmanager +from datetime import datetime, timezone +from typing import Any, Iterator, Optional, Union +from unittest import mock + +import pytest +from requests import Response + +from posthog import AsyncPosthog, CaptureCompression, Client +from posthog.capture_send import ( + _CAPTURE_AI_V1_PATH, + _CAPTURE_V1_PATH, + _HEADER_REQUEST_TIMESTAMP, +) + +_UUID = "01890000-0000-7000-8000-000000000001" +_TIMESTAMP = "2026-01-02T03:04:05+00:00" + + +def _event_kwargs() -> dict[str, Any]: + return { + "distinct_id": "user-1", + "uuid": _UUID, + "timestamp": _TIMESTAMP, + "properties": { + "$process_person_profile": False, + "$product_tour_id": "tour-1", + "empty_list": [], + "empty_map": {}, + "none": None, + "nested": {"a": {"b": [1, None, {}]}}, + }, + "options": { + "process_person_profile": None, + "cookieless_mode": False, + "custom_list": [], + "custom_map": {"inner": {}}, + }, + } + + +def _ok_response(events: list[dict]) -> Response: + response = Response() + response.status_code = 200 + response._content = json.dumps( + {"results": {event["uuid"]: {"result": "ok"} for event in events}} + ).encode() + return response + + +def _record_wire(sent: list[tuple[str, list[dict]]]): + def post(url, data=None, **kwargs): + events = json.loads(data)["batch"] + sent.append((url, events)) + return _ok_response(events) + + session = mock.Mock() + session.post.side_effect = post + return mock.patch("posthog.capture_send._get_capture_session", return_value=session) + + +def _record_requests(requests: list[dict[str, Any]]): + def post(url, data=None, headers=None, **kwargs): + body = json.loads(data) + requests.append({"body": body, "headers": headers}) + return _ok_response(body["batch"]) + + session = mock.Mock() + session.post.side_effect = post + return mock.patch("posthog.capture_send._get_capture_session", return_value=session) + + +def _send_sync(method_name: str, before_send) -> list[tuple[str, list[dict]]]: + sent: list[tuple[str, list[dict]]] = [] + with _record_wire(sent): + client = Client( + "test-key", + sync_mode=True, + before_send=before_send, + capture_compression=CaptureCompression.NONE, + ) + assert getattr(client, method_name)("$ai_generation", **_event_kwargs()) + client.shutdown() + return sent + + +async def _send_async(method_name: str, before_send) -> list[tuple[str, list[dict]]]: + sent: list[tuple[str, list[dict]]] = [] + with _record_wire(sent): + client = AsyncPosthog( + "test-key", + before_send=before_send, + capture_compression=CaptureCompression.NONE, + ) + assert await getattr(client, method_name)("$ai_generation", **_event_kwargs()) + await client.shutdown() + return sent + + +def _pass_through(event: dict) -> Optional[dict]: + return event + + +@pytest.mark.parametrize( + ("method_name", "path"), + [("capture", _CAPTURE_V1_PATH), ("capture_ai", _CAPTURE_AI_V1_PATH)], +) +def test_pass_through_before_send_leaves_sync_wire_unchanged(method_name, path): + without_hook = _send_sync(method_name, None) + with_hook = _send_sync(method_name, _pass_through) + + assert [url.endswith(path) for url, _ in without_hook] == [True] + assert with_hook == without_hook + assert without_hook[0][1][0]["options"]["process_person_profile"] is False + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + ("method_name", "path"), + [ + ("capture_immediate", _CAPTURE_V1_PATH), + ("capture_ai_immediate", _CAPTURE_AI_V1_PATH), + ], +) +async def test_pass_through_before_send_leaves_async_wire_unchanged(method_name, path): + without_hook = await _send_async(method_name, None) + with_hook = await _send_async(method_name, _pass_through) + + assert [url.endswith(path) for url, _ in without_hook] == [True] + assert with_hook == without_hook + assert without_hook[0][1][0]["options"]["process_person_profile"] is False + + +_WHOLE_SECOND = datetime(2026, 1, 2, 3, 4, 5, tzinfo=timezone.utc) +_WHOLE_SECOND_WIRE = "2026-01-02T03:04:05.000000+00:00" + + +@contextmanager +def _whole_second_clock() -> Iterator[None]: + """Freeze ``datetime.now`` at a whole second where capture reads the clock.""" + with ExitStack() as stack: + for module in ("client", "async_client", "capture_send"): + stack.enter_context( + mock.patch( + f"posthog.{module}.datetime", + wraps=datetime, + **{"now.return_value": _WHOLE_SECOND}, + ) + ) + yield + + +def _capture_on_path( + path: str, timestamp: Union[str, datetime, None] +) -> list[dict[str, Any]]: + requests: list[dict[str, Any]] = [] + kwargs: dict[str, Any] = {"distinct_id": "user-1", "timestamp": timestamp} + with _record_requests(requests), _whole_second_clock(): + if path == "async": + + async def send() -> None: + client = AsyncPosthog( + "test-key", capture_compression=CaptureCompression.NONE + ) + assert client.capture("event", **kwargs) + await client.shutdown() + + asyncio.run(send()) + else: + client = Client( + "test-key", + sync_mode=path == "sync_mode", + capture_compression=CaptureCompression.NONE, + ) + assert client.capture("event", **kwargs) + client.shutdown() + return requests + + +@pytest.mark.parametrize("path", ["sync_mode", "sync", "async"]) +@pytest.mark.parametrize( + ("timestamp", "expected"), + [ + (None, _WHOLE_SECOND_WIRE), + ("not-an-iso-timestamp", _WHOLE_SECOND_WIRE), + (_WHOLE_SECOND, _WHOLE_SECOND_WIRE), + ("2026-01-02T03:04:05Z", _WHOLE_SECOND_WIRE), + ("2026-01-02T03:04:05.000Z", _WHOLE_SECOND_WIRE), + ("2026-01-02T03:04:05.120Z", "2026-01-02T03:04:05.120000+00:00"), + ("2026-01-02T03:04:05.123456Z", "2026-01-02T03:04:05.123456+00:00"), + ], +) +def test_wire_timestamps_keep_fractional_digits_on_whole_seconds( + path, timestamp, expected +): + requests = _capture_on_path(path, timestamp) + + assert len(requests) == 1 + body, headers = requests[0]["body"], requests[0]["headers"] + assert [event["timestamp"] for event in body["batch"]] == [expected] + assert body["created_at"] == _WHOLE_SECOND_WIRE + assert headers[_HEADER_REQUEST_TIMESTAMP] == _WHOLE_SECOND_WIRE diff --git a/posthog/test/test_capture_mode.py b/posthog/test/test_capture_mode.py deleted file mode 100644 index 473e1a886..000000000 --- a/posthog/test/test_capture_mode.py +++ /dev/null @@ -1,109 +0,0 @@ -import os -import unittest -from unittest import mock - -from parameterized import parameterized - -from posthog.capture_mode import ( - CAPTURE_MODE_ENV_VAR, - CaptureMode, - _resolve_capture_mode, -) -from posthog.client import Client -from posthog.consumer import Consumer -from posthog.test.logging_helpers import capture_message_only_logs -from posthog.test.test_utils import TEST_API_KEY - - -class TestResolveCaptureMode(unittest.TestCase): - def test_defaults_to_v0_with_no_kwarg_and_no_env(self) -> None: - with mock.patch.dict(os.environ, {}, clear=False): - os.environ.pop(CAPTURE_MODE_ENV_VAR, None) - self.assertIs(_resolve_capture_mode(None), CaptureMode.V0) - - @parameterized.expand( - [ - # (name, kwarg, expected, opposite_env): the env always names the - # mode the kwarg must override, so every row proves the kwarg wins. - ("enum_v0", CaptureMode.V0, CaptureMode.V0, "v1"), - ("enum_v1", CaptureMode.V1, CaptureMode.V1, "v0"), - ("str_v0", "v0", CaptureMode.V0, "v1"), - ("str_v1", "v1", CaptureMode.V1, "v0"), - ("str_legacy_alias", "legacy", CaptureMode.V0, "v1"), - ("str_analytics_v1_alias", "analytics_v1", CaptureMode.V1, "v0"), - ("str_upper_and_padded", " V1 ", CaptureMode.V1, "v0"), - ] - ) - def test_explicit_kwarg_takes_precedence_and_coerces( - self, _name, kwarg, expected, opposite_env - ) -> None: - with mock.patch.dict(os.environ, {CAPTURE_MODE_ENV_VAR: opposite_env}): - self.assertIs(_resolve_capture_mode(kwarg), expected) - - def test_invalid_kwarg_raises_even_with_valid_env(self) -> None: - # The kwarg path is consulted before the env, so an invalid kwarg raises - # rather than silently falling back to a valid env value. - with mock.patch.dict(os.environ, {CAPTURE_MODE_ENV_VAR: "v1"}): - with self.assertRaises(ValueError): - _resolve_capture_mode("bogus") - - @parameterized.expand( - [ - ("v0", "v0", CaptureMode.V0), - ("legacy", "legacy", CaptureMode.V0), - ("v1", "v1", CaptureMode.V1), - ("analytics_v1", "analytics_v1", CaptureMode.V1), - ("uppercase", "V1", CaptureMode.V1), - ("padded", " v1 ", CaptureMode.V1), - ] - ) - def test_env_var_resolution(self, _name, env_value, expected) -> None: - with mock.patch.dict(os.environ, {CAPTURE_MODE_ENV_VAR: env_value}): - self.assertIs(_resolve_capture_mode(None), expected) - - @parameterized.expand([("empty", ""), ("whitespace", " ")]) - def test_blank_env_var_defaults_to_v0(self, _name, env_value) -> None: - with mock.patch.dict(os.environ, {CAPTURE_MODE_ENV_VAR: env_value}): - self.assertIs(_resolve_capture_mode(None), CaptureMode.V0) - - def test_unrecognized_env_var_warns_and_defaults_to_v0(self) -> None: - with mock.patch.dict(os.environ, {CAPTURE_MODE_ENV_VAR: "bogus"}): - with capture_message_only_logs() as stream: - self.assertIs(_resolve_capture_mode(None), CaptureMode.V0) - self.assertIn("bogus", stream.getvalue()) - - @parameterized.expand([("bad_str", "bogus"), ("wrong_type", 1)]) - def test_invalid_explicit_kwarg_raises(self, _name, value) -> None: - with self.assertRaises(ValueError): - _resolve_capture_mode(value) - - -class TestCaptureModePlumbing(unittest.TestCase): - def test_client_resolves_and_stores_default_v0(self) -> None: - with mock.patch.dict(os.environ, {}, clear=False): - os.environ.pop(CAPTURE_MODE_ENV_VAR, None) - client = Client(TEST_API_KEY, sync_mode=True) - self.assertIs(client.capture_mode, CaptureMode.V0) - - @parameterized.expand( - [ - ("enum_v1", CaptureMode.V1, CaptureMode.V1), - ("str_v1", "v1", CaptureMode.V1), - ("enum_v0", CaptureMode.V0, CaptureMode.V0), - ] - ) - def test_client_kwarg_sets_mode(self, _name, kwarg, expected) -> None: - client = Client(TEST_API_KEY, sync_mode=True, capture_mode=kwarg) - self.assertIs(client.capture_mode, expected) - - def test_client_propagates_mode_to_consumers(self) -> None: - # Async (non-sync) client builds Consumer threads; assert each carries - # the resolved mode. - client = Client(TEST_API_KEY, capture_mode=CaptureMode.V1, send=False, thread=2) - self.assertEqual(len(client.consumers), 2) - for consumer in client.consumers: - self.assertIs(consumer.capture_mode, CaptureMode.V1) - - def test_consumer_defaults_to_v0(self) -> None: - consumer = Consumer(None, TEST_API_KEY) - self.assertIs(consumer.capture_mode, CaptureMode.V0) diff --git a/posthog/test/test_capture_send.py b/posthog/test/test_capture_send.py new file mode 100644 index 000000000..8ed642a30 --- /dev/null +++ b/posthog/test/test_capture_send.py @@ -0,0 +1,929 @@ +import json +import unittest +import zlib +from datetime import datetime, timedelta +from unittest import mock +from uuid import UUID + +import zstandard + +from requests.adapters import HTTPAdapter + +from parameterized import parameterized + +from posthog import capture_send +from posthog.capture_compression import CaptureCompression +from posthog.capture_event import _build_v1_batch_body, _to_v1_event +from posthog.capture_send import ( + _CAPTURE_AI_V1_PATH, + _CAPTURE_V1_PATH, + _HEADER_ATTEMPT, + _HEADER_REQUEST_ID, + _HEADER_REQUEST_TIMESTAMP, + _HEADER_SDK_INFO, + _MAX_BACKOFF_SECONDS, + CaptureError, + CaptureEventResult, + _capture_loss_message, + _parse_v1_response, + _post_v1, + _send_v1_batch, + _backoff, +) +from posthog.request import USER_AGENT + + +class _FakeResponse: + """Minimal stand-in for ``requests.Response`` for transport tests.""" + + def __init__( + self, status_code, *, json_body=None, headers=None, text="", raise_json=False + ): + self.status_code = status_code + self.headers = headers or {} + self.text = text + self._json_body = json_body + self._raise_json = raise_json + + def json(self): + if self._raise_json: + raise ValueError("no json") + return self._json_body + + +class _RecordingSession: + """Records each ``.post`` and returns canned responses, repeating the last.""" + + def __init__(self, *responses): + self._responses = list(responses) + self.calls = [] + + def post(self, url, data=None, headers=None, timeout=None, allow_redirects=True): + self.calls.append( + { + "url": url, + "data": data, + "headers": headers, + "timeout": timeout, + "allow_redirects": allow_redirects, + } + ) + return self._responses[min(len(self.calls), len(self._responses)) - 1] + + +class _PostV1Stub: + """Drop-in for ``_post_v1`` that records calls and replays canned outcomes. + + Each item in ``outcomes`` is either a ``_FakeResponse`` to return or an + ``Exception`` instance to raise (simulating a transport failure). + """ + + def __init__(self, outcomes): + self._outcomes = list(outcomes) + self.calls = [] + + def __call__( + self, + api_key, + host, + batch_body, + *, + attempt, + request_id, + compression=CaptureCompression.NONE, + timeout=15, + sdk_info=USER_AGENT, + session=None, + path=_CAPTURE_V1_PATH, + ): + self.calls.append( + { + "path": path, + "attempt": attempt, + "request_id": request_id, + "compression": compression, + "sdk_info": sdk_info, + "created_at": batch_body["created_at"], + "uuids": [e["uuid"] for e in batch_body["batch"]], + } + ) + outcome = self._outcomes[len(self.calls) - 1] + if isinstance(outcome, Exception): + raise outcome + return outcome + + +_DUP_A = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa" + + +def _msg(uuid, event="e", **overrides): + msg = { + "event": event, + "uuid": uuid, + "distinct_id": "user-1", + "timestamp": "2026-06-27T12:00:00+00:00", + "type": "capture", + "properties": {}, + } + msg.update(overrides) + return msg + + +def _results_response(directives, headers=None, duplicates_dropped=None): + """200 response whose ``results`` map tags each uuid. + + ``directives`` maps uuid -> ``"ok"`` (or any result string) or a + ``(result, details)`` tuple. ``duplicates_dropped`` maps uuid -> count. + """ + results = {} + for uid, spec in directives.items(): + result, details = spec if isinstance(spec, tuple) else (spec, None) + results[uid] = {"result": result, "details": details} + for uid, count in (duplicates_dropped or {}).items(): + results[uid]["duplicates_dropped"] = count + return _FakeResponse(200, json_body={"results": results}, headers=headers) + + +class TestPostV1(unittest.TestCase): + def _post(self, response, **kwargs): + session = _RecordingSession(response) + body = _build_v1_batch_body([_to_v1_event(_msg("u-1"))]) + _post_v1( + "phc_key", + "https://app.posthog.com/", + body, + attempt=2, + request_id="req-123", + session=session, + **kwargs, + ) + return session.calls[0] + + def test_url_uses_v1_path_and_trims_host(self) -> None: + call = self._post(_results_response({})) + self.assertEqual(call["url"], "https://app.posthog.com" + _CAPTURE_V1_PATH) + call = self._post(_results_response({}), path=_CAPTURE_AI_V1_PATH) + self.assertEqual(call["url"], "https://app.posthog.com" + _CAPTURE_AI_V1_PATH) + + def test_required_headers_present(self) -> None: + headers = self._post(_results_response({}))["headers"] + self.assertEqual(headers["Authorization"], "Bearer phc_key") + self.assertEqual(headers[_HEADER_ATTEMPT], "2") + self.assertEqual(headers[_HEADER_REQUEST_ID], "req-123") + self.assertTrue(headers[_HEADER_SDK_INFO].startswith("posthog-python/")) + self.assertEqual(headers["Content-Type"], "application/json") + request_timestamp = datetime.fromisoformat(headers[_HEADER_REQUEST_TIMESTAMP]) + self.assertEqual(request_timestamp.utcoffset(), timedelta(0)) + + def test_custom_sdk_info_headers(self) -> None: + headers = self._post(_results_response({}), sdk_info="posthog-python/9.9.9")[ + "headers" + ] + self.assertEqual(headers[_HEADER_SDK_INFO], "posthog-python/9.9.9") + self.assertEqual(headers["User-Agent"], "posthog-python/9.9.9") + + def test_non_finite_floats_are_sent_as_null(self) -> None: + session = _RecordingSession(_results_response({})) + event = _msg( + "u-1", properties={"score": float("inf"), "nested": [float("nan"), 1.5]} + ) + _post_v1( + "phc_key", + "https://app.posthog.com/", + _build_v1_batch_body([_to_v1_event(event)]), + attempt=1, + request_id="req-123", + session=session, + ) + body = json.loads( + session.calls[0]["data"], + parse_constant=lambda token: (_ for _ in ()).throw(ValueError(token)), + ) + properties = body["batch"][0]["properties"] + self.assertIsNone(properties["score"]) + self.assertEqual(properties["nested"], [None, 1.5]) + + def test_no_api_key_in_body(self) -> None: + # v1 authenticates via the Bearer header; the key must not leak into the body. + data = self._post(_results_response({}))["data"] + self.assertNotIn("phc_key", data) + self.assertNotIn("api_key", json.loads(data)) + + def test_uncompressed_body_is_json_str_without_encoding_header(self) -> None: + call = self._post(_results_response({}), compression=CaptureCompression.NONE) + self.assertIsInstance(call["data"], str) + self.assertNotIn("Content-Encoding", call["headers"]) + + def test_gzip_sets_encoding_header_and_compresses_body(self) -> None: + call = self._post(_results_response({}), compression=CaptureCompression.GZIP) + self.assertEqual(call["headers"]["Content-Encoding"], "gzip") + self.assertIsInstance(call["data"], bytes) + self.assertEqual(call["data"][:2], b"\x1f\x8b") # gzip magic + + def test_deflate_sets_encoding_header_and_zlib_wraps_body(self) -> None: + # Must be zlib-wrapped (RFC 1950, 0x78 prefix), matching posthog-go / + # posthog-rs, so the server routes Content-Encoding: deflate to its zlib + # decoder rather than treating it as raw deflate. + call = self._post(_results_response({}), compression=CaptureCompression.DEFLATE) + self.assertEqual(call["headers"]["Content-Encoding"], "deflate") + self.assertIsInstance(call["data"], bytes) + self.assertEqual(call["data"][0], 0x78) # zlib header + roundtripped = zlib.decompress(call["data"]).decode("utf-8") + self.assertNotIn("api_key", json.loads(roundtripped)) + + def test_zstd_sets_encoding_header_and_emits_standard_frame(self) -> None: + call = self._post(_results_response({}), compression=CaptureCompression.ZSTD) + self.assertEqual(call["headers"]["Content-Encoding"], "zstd") + self.assertIsInstance(call["data"], bytes) + self.assertEqual(call["data"][:4], b"\x28\xb5\x2f\xfd") # zstd frame magic + roundtripped = zstandard.ZstdDecompressor().decompress(call["data"]) + body = json.loads(roundtripped.decode("utf-8")) + self.assertNotIn("api_key", body) + self.assertEqual(len(body["batch"]), 1) + + def test_zstd_without_package_raises_actionable_error(self) -> None: + with mock.patch("posthog.capture_send._zstandard", None): + with self.assertRaises(ValueError) as ctx: + self._post(_results_response({}), compression=CaptureCompression.ZSTD) + self.assertIn("posthog[zstd]", str(ctx.exception)) + + @parameterized.expand( + [ + ( + "relative_location", + "https://us.i.posthog.com", + "/i/v1/analytics/events?retry=1", + "https://us.i.posthog.com/i/v1/analytics/events?retry=1", + ), + ( + "host_path_prefix", + "https://example.com/ingest", + "https://example.com/ingest/i/v1/analytics/events", + "https://example.com/ingest/i/v1/analytics/events", + ), + ( + "explicit_default_port", + "https://us.i.posthog.com", + "https://us.i.posthog.com:443/other", + "https://us.i.posthog.com/other", + ), + ( + "unicode_host_idna_location", + "https://bücher.example", + "https://xn--bcher-kva.example/ingest", + "https://bücher.example/ingest", + ), + ( + "idna_host_unicode_location", + "https://xn--bcher-kva.example", + "https://bücher.example/ingest", + "https://xn--bcher-kva.example/ingest", + ), + ] + ) + def test_follows_same_origin_redirect_with_same_body( + self, _name, host, location, expected_url + ) -> None: + final = _results_response({}) + session = _RecordingSession( + _FakeResponse(307, headers={"Location": location}), final + ) + body = _build_v1_batch_body([_to_v1_event(_msg("u-1"))]) + res = _post_v1( + "phc_key", host, body, attempt=1, request_id="r", session=session + ) + + self.assertIs(res, final) + self.assertEqual([c["url"] for c in session.calls][1], expected_url) + self.assertEqual(session.calls[0]["data"], session.calls[1]["data"]) + self.assertEqual(session.calls[0]["headers"], session.calls[1]["headers"]) + self.assertTrue(all(c["allow_redirects"] is False for c in session.calls)) + + @parameterized.expand( + [ + ("other_host", 307, "https://attacker.example.com/collect"), + ("other_unicode_host", 307, "https://bücher-andere.example/collect"), + ("loopback", 308, "http://127.0.0.1:8080/collect"), + ("https_to_http", 307, "http://us.i.posthog.com/i/v1/analytics/events"), + ("other_port", 308, "https://us.i.posthog.com:8443/i/v1/analytics/events"), + ("missing_location", 307, None), + ("not_307_or_308", 302, "/i/v1/analytics/events"), + ] + ) + def test_does_not_follow_other_redirects(self, _name, status, location) -> None: + redirect = _FakeResponse( + status, headers={"Location": location} if location else {} + ) + session = _RecordingSession(redirect, _results_response({})) + body = _build_v1_batch_body([_to_v1_event(_msg("u-1"))]) + # Failed-batch reporting owns warnings, so the transport logs nothing here. + with self.assertNoLogs("posthog", level="WARNING"): + res = _post_v1( + "phc_key", + "https://us.i.posthog.com", + body, + attempt=1, + request_id="r", + session=session, + ) + + self.assertIs(res, redirect) + self.assertEqual(len(session.calls), 1) + + def test_stops_after_max_redirects(self) -> None: + loop = _FakeResponse(307, headers={"Location": "/i/v1/analytics/events"}) + session = _RecordingSession(loop) + body = _build_v1_batch_body([_to_v1_event(_msg("u-1"))]) + with self.assertNoLogs("posthog", level="WARNING"): + res = _post_v1( + "phc_key", + "https://us.i.posthog.com", + body, + attempt=1, + request_id="r", + session=session, + ) + + self.assertIs(res, loop) + self.assertEqual(len(session.calls), 6) + + +class TestParseV1Response(unittest.TestCase): + def test_success_parses_results_with_details(self) -> None: + res = _FakeResponse( + 200, + json_body={"results": {"u-1": {"result": "drop", "details": "spam"}}}, + ) + parsed = _parse_v1_response(res) + self.assertTrue(parsed.is_success) + self.assertEqual(parsed.results["u-1"].result, "drop") + self.assertEqual(parsed.results["u-1"].details, "spam") + + def test_success_parses_duplicates_dropped(self) -> None: + res = _results_response( + {"u-1": "ok", "u-2": "ok"}, duplicates_dropped={"u-1": 2} + ) + parsed = _parse_v1_response(res) + self.assertEqual(parsed.duplicates_dropped, {"u-1": 2}) + self.assertEqual(parsed.results["u-1"], CaptureEventResult("ok")) + + @parameterized.expand( + [ + ("string", "2"), + ("bool", True), + ("negative", -1), + ("zero", 0), + ("float", 2.0), + ("null", None), + ] + ) + def test_invalid_duplicates_dropped_ignored(self, _name, value) -> None: + res = _results_response({"u-1": "ok"}, duplicates_dropped={"u-1": value}) + parsed = _parse_v1_response(res) + self.assertFalse(parsed.malformed) + self.assertEqual(parsed.duplicates_dropped, {}) + self.assertEqual(parsed.results["u-1"], CaptureEventResult("ok")) + + @parameterized.expand( + [ + ("unparseable_body", _FakeResponse(200, raise_json=True)), + ("missing_results_key", _FakeResponse(200, json_body={"foo": 1})), + ] + ) + def test_success_with_bad_body_is_malformed(self, _name, res) -> None: + parsed = _parse_v1_response(res) + self.assertTrue(parsed.is_success) + self.assertTrue(parsed.malformed) + + @parameterized.expand( + [ + ("error_description", {"error_description": "bad batch"}, "bad batch"), + ("error", {"error": "validation_error"}, "validation_error"), + ("detail", {"detail": "nope"}, "nope"), + ] + ) + def test_error_message_extracted_from_body(self, _name, body, expected) -> None: + parsed = _parse_v1_response(_FakeResponse(400, json_body=body)) + self.assertFalse(parsed.is_success) + self.assertEqual(parsed.error_message, expected) + + def test_error_message_falls_back_to_text(self) -> None: + parsed = _parse_v1_response(_FakeResponse(400, raise_json=True, text="boom")) + self.assertEqual(parsed.error_message, "boom") + + @parameterized.expand([("numeric", "2", 2.0), ("absent", None, None)]) + def test_retry_after_header(self, _name, header_value, expected) -> None: + headers = {"Retry-After": header_value} if header_value is not None else {} + parsed = _parse_v1_response(_FakeResponse(503, headers=headers)) + self.assertEqual(parsed.retry_after, expected) + + +class TestSendV1Batch(unittest.TestCase): + """Drives ``_send_v1_batch`` with a stubbed ``_post_v1`` and no real sleeps.""" + + def setUp(self) -> None: + sleep_patch = mock.patch("posthog.capture_send.time.sleep") + self.sleep = sleep_patch.start() + self.addCleanup(sleep_patch.stop) + _patch_no_jitter(self) + + def _run(self, batch, outcomes, **kwargs): + stub = _PostV1Stub(outcomes) + with mock.patch("posthog.capture_send._post_v1", stub): + _send_v1_batch("phc_key", "https://app.posthog.com", batch, **kwargs) + return stub + + def _run_expecting_error(self, batch, outcomes, **kwargs): + stub = _PostV1Stub(outcomes) + with mock.patch("posthog.capture_send._post_v1", stub): + with self.assertRaises(CaptureError) as ctx: + _send_v1_batch("phc_key", "https://app.posthog.com", batch, **kwargs) + return stub, ctx.exception + + def test_all_ok_sends_once(self) -> None: + stub = self._run([_msg("u-1")], [_results_response({"u-1": "ok"})]) + self.assertEqual(len(stub.calls), 1) + self.sleep.assert_not_called() + + def test_custom_sdk_info_is_forwarded(self) -> None: + stub = self._run( + [_msg("u-1")], + [_results_response({"u-1": "ok"})], + sdk_info="posthog-python/9.9.9", + ) + self.assertEqual(stub.calls[0]["sdk_info"], "posthog-python/9.9.9") + + def test_absent_uuid_treated_as_accepted(self) -> None: + # Empty results map: the event is neither retried nor errored. + stub = self._run([_msg("u-1")], [_results_response({})]) + self.assertEqual(len(stub.calls), 1) + + def test_partial_retry_resends_only_retry_events(self) -> None: + batch = [_msg("u-ok"), _msg("u-retry")] + stub = self._run( + batch, + [ + _results_response({"u-ok": "ok", "u-retry": "retry"}), + _results_response({"u-retry": "ok"}), + ], + ) + self.assertEqual(len(stub.calls), 2) + self.assertEqual(stub.calls[0]["uuids"], ["u-ok", "u-retry"]) + # Second attempt carries only the event the server asked to retry. + self.assertEqual(stub.calls[1]["uuids"], ["u-retry"]) + + def test_request_id_and_created_at_stable_attempt_increments(self) -> None: + stub = self._run( + [_msg("u-1")], + [ + _results_response({"u-1": "retry"}), + _results_response({"u-1": "ok"}), + ], + ) + self.assertEqual(stub.calls[0]["request_id"], stub.calls[1]["request_id"]) + self.assertEqual(UUID(stub.calls[0]["request_id"]).version, 7) + # created_at is hoisted once, so the envelope timestamp is identical + # across retry attempts (only the attempt header increments). + self.assertEqual(stub.calls[0]["created_at"], stub.calls[1]["created_at"]) + self.assertEqual([c["attempt"] for c in stub.calls], [1, 2]) + + def test_compression_and_path_forwarded_to_post_v1(self) -> None: + stub = self._run( + [_msg("u-1")], + [_results_response({"u-1": "ok"})], + compression=CaptureCompression.DEFLATE, + path=_CAPTURE_AI_V1_PATH, + ) + self.assertEqual(stub.calls[0]["compression"], CaptureCompression.DEFLATE) + self.assertEqual(stub.calls[0]["path"], _CAPTURE_AI_V1_PATH) + + def test_drop_on_2xx_surfaces_via_error(self) -> None: + # A server-chosen drop is terminal: even on an all-ok-otherwise 2xx with + # no retry events, the send raises so on_error sees the dropped uuid + # (matches posthog-go/posthog-rs — a 2xx is not full delivery). + batch = [_msg("u-ok"), _msg("u-drop")] + stub, exc = self._run_expecting_error( + batch, + [_results_response({"u-ok": "ok", "u-drop": ("drop", "invalid")})], + ) + self.assertEqual(len(stub.calls), 1) # terminal, not retried + self.assertEqual(exc.status, 200) + self.assertEqual(exc.drops, [("u-drop", "invalid")]) + self.assertEqual( + (exc.drops[0].uuid, exc.drops[0].details), ("u-drop", "invalid") + ) + self.assertEqual(exc.retry_exhausted, []) + + def test_all_ok_no_drops_does_not_raise(self) -> None: + # The success path is unchanged when the server drops nothing. + stub = self._run( + [_msg("u-1"), _msg("u-2")], + [_results_response({"u-1": "ok", "u-2": "warning"})], + ) + self.assertEqual(len(stub.calls), 1) + + def test_drop_accumulated_across_attempts_surfaces_on_later_success(self) -> None: + # Attempt 1 drops one event and retries another; attempt 2 clears the + # retry. The earlier drop must still surface — it is not lost when the + # outstanding retries succeed on a later 2xx. + batch = [_msg("u-drop"), _msg("u-retry")] + stub, exc = self._run_expecting_error( + batch, + [ + _results_response( + {"u-drop": ("drop", "llm_events_over_quota"), "u-retry": "retry"} + ), + _results_response({"u-retry": "ok"}), + ], + ) + self.assertEqual(len(stub.calls), 2) + self.assertEqual(stub.calls[1]["uuids"], ["u-retry"]) # only retry resent + self.assertEqual(exc.drops, [("u-drop", "llm_events_over_quota")]) + self.assertEqual(exc.retry_exhausted, []) + + def test_retry_exhausted_raises_with_uuids(self) -> None: + stub, exc = self._run_expecting_error( + [_msg("u-1")], + [_results_response({"u-1": "retry"}), _results_response({"u-1": "retry"})], + max_retries=1, + ) + self.assertEqual(len(stub.calls), 2) + self.assertEqual(exc.retry_exhausted, ["u-1"]) + self.assertEqual(exc.drops, []) + + def test_retry_exhausted_carries_earlier_drops(self) -> None: + # A drop seen on attempt 1 rides along on the retry-exhaustion error. + batch = [_msg("u-ok"), _msg("u-drop"), _msg("u-retry")] + stub, exc = self._run_expecting_error( + batch, + [ + _results_response( + { + "u-ok": "ok", + "u-drop": ("drop", "llm_events_over_quota"), + "u-retry": "retry", + } + ), + _results_response({"u-retry": ("retry", "not_persisted")}), + ], + max_retries=1, + ) + self.assertEqual(len(stub.calls), 2) + self.assertEqual(exc.endpoint, _CAPTURE_V1_PATH) + self.assertEqual(exc.retry_exhausted, ["u-retry"]) + self.assertEqual(exc.drops, [("u-drop", "llm_events_over_quota")]) + self.assertEqual( + exc.event_results, + { + "u-ok": CaptureEventResult("ok"), + "u-drop": CaptureEventResult("drop", "llm_events_over_quota"), + "u-retry": CaptureEventResult("retry", "not_persisted"), + }, + ) + self.assertEqual( + exc.verdict_summary(), "drop/llm_events_over_quota=1, retry/not_persisted=1" + ) + + @parameterized.expand( + [ + ("uppercase", "AAAAAAAA-AAAA-4AAA-8AAA-AAAAAAAAAAAA"), + ("no_hyphens", "aaaaaaaaaaaa4aaa8aaaaaaaaaaaaaaa"), + ("braced", "{aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa}"), + ("urn", "urn:uuid:aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"), + ] + ) + def test_results_match_non_canonical_uuid(self, _name, sent_uuid) -> None: + # Capture parses any of these forms but keys results canonically, so a + # verdict for a uuid `before_send` rewrote must still reach its event. + canonical = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa" + stub, exc = self._run_expecting_error( + [_msg(sent_uuid)], + [ + _results_response({canonical: "retry"}), + _results_response({canonical: ("drop", "llm_events_over_quota")}), + ], + ) + self.assertEqual(len(stub.calls), 2) + self.assertEqual(exc.drops, [(canonical, "llm_events_over_quota")]) + + @parameterized.expand( + [ + ("kept_ok", "ok", 2, [], [], [], CaptureEventResult("ok"), ""), + ( + "kept_warning", + "warning", + 2, + [], + [], + [], + CaptureEventResult("warning"), + "", + ), + ( + "kept_drop", + ("drop", "invalid_options"), + 2, + [], + [], + [(_DUP_A, "invalid_options")], + CaptureEventResult("drop", "invalid_options"), + ", drop/invalid_options=1", + ), + ( + "kept_retry_then_ok", + "retry", + 2, + [_results_response({_DUP_A: "ok"})], + [[_DUP_A]], + [], + CaptureEventResult("ok"), + "", + ), + ( + "copy_past_count_keeps_kept_verdict", + "retry", + 1, + [_results_response({_DUP_A: "ok"}, duplicates_dropped={_DUP_A: 1})], + [[_DUP_A, _DUP_A]], + [], + CaptureEventResult("ok"), + "", + ), + ] + ) + def test_duplicates_dropped_reported_as_drops( + self, _name, kept, count, later, resent, kept_drops, kept_result, summary_rest + ) -> None: + batch = [_msg(_DUP_A), _msg("u-b"), _msg(_DUP_A.upper()), _msg(_DUP_A)] + first = _results_response( + {_DUP_A: kept, "u-b": "ok"}, duplicates_dropped={_DUP_A: count} + ) + stub, exc = self._run_expecting_error(batch, [first, *later]) + + self.assertEqual([c["uuids"] for c in stub.calls[1:]], resent) + duplicate = (_DUP_A, "duplicate_event_uuid") + self.assertEqual(exc.drops, kept_drops + [duplicate, duplicate]) + self.assertEqual( + exc.event_results, + {_DUP_A: kept_result, "u-b": CaptureEventResult("ok")}, + ) + self.assertEqual( + exc.verdict_summary(), "drop/duplicate_event_uuid=2" + summary_rest + ) + + def test_malformed_2xx_is_terminal(self) -> None: + stub, exc = self._run_expecting_error( + [_msg("u-1")], [_FakeResponse(200, raise_json=True)] + ) + self.assertEqual(len(stub.calls), 1) + self.assertEqual(exc.status, 200) + + @parameterized.expand( + [ + ("bad_request", 400), + ("billing_limit", 402), + ("unfollowed_redirect", 307), + ("unfollowed_permanent_redirect", 308), + ] + ) + def test_terminal_status_raises_immediately(self, _name, status) -> None: + stub, exc = self._run_expecting_error( + [_msg("u-1")], + [_FakeResponse(status, json_body={"error": "nope"})], + max_retries=2, + ) + self.assertEqual(len(stub.calls), 1) # not retried + self.assertEqual(exc.status, status) + + @parameterized.expand( + [("not_found", 404), ("rate_limited", 429), ("unavailable", 503)] + ) + def test_retryable_status_then_success(self, _name, status) -> None: + stub = self._run( + [_msg("u-1")], + [ + _FakeResponse(status, headers={"Retry-After": "2"}), + _results_response({"u-1": "ok"}), + ], + ) + self.assertEqual(len(stub.calls), 2) + self.sleep.assert_called_once_with(2.0) # honored Retry-After + + @parameterized.expand( + [("not_found", 404), ("rate_limited", 429), ("unavailable", 503)] + ) + def test_retryable_status_exhausted_raises(self, _name, status) -> None: + stub, exc = self._run_expecting_error( + [_msg("u-1")], [_FakeResponse(status), _FakeResponse(status)], max_retries=1 + ) + self.assertEqual(len(stub.calls), 2) + self.assertEqual(exc.status, status) + + def test_transport_error_then_success(self) -> None: + stub = self._run( + [_msg("u-1")], + [ConnectionError("boom"), _results_response({"u-1": "ok"})], + ) + self.assertEqual(len(stub.calls), 2) + + def test_transport_error_exhausted_raises_capture_error(self) -> None: + stub = _PostV1Stub([ConnectionError("boom"), ConnectionError("boom")]) + with mock.patch("posthog.capture_send._post_v1", stub): + with self.assertRaises(CaptureError) as ctx: + _send_v1_batch( + "phc_key", + "https://app.posthog.com", + [_msg("u-1")], + max_retries=1, + path=_CAPTURE_AI_V1_PATH, + ) + self.assertEqual(len(stub.calls), 2) + self.assertEqual(ctx.exception.status, 0) + self.assertEqual(ctx.exception.endpoint, _CAPTURE_AI_V1_PATH) + self.assertEqual(ctx.exception.attempts, 2) + self.assertIsInstance(ctx.exception.__cause__, ConnectionError) + + def test_refused_connection_is_retried_by_the_sdk_not_the_http_adapter( + self, + ) -> None: + # Each physical try must be its own SDK attempt, so capture gets a fresh request timestamp. + sent_attempts = [] + real_send = HTTPAdapter.send + + def record_send(adapter, request, **kwargs): + sent_attempts.append(request.headers[_HEADER_ATTEMPT]) + return real_send(adapter, request, **kwargs) + + with ( + mock.patch.object(HTTPAdapter, "send", record_send), + mock.patch( + "urllib3.util.connection.create_connection", + side_effect=ConnectionRefusedError, + ) as connect, + self.assertRaises(CaptureError) as ctx, + ): + _send_v1_batch( + "phc_key", "https://app.posthog.com", [_msg("u-1")], max_retries=2 + ) + + self.assertEqual(sent_attempts, ["1", "2", "3"]) + self.assertEqual(connect.call_count, 3) + self.assertEqual(ctx.exception.attempts, 3) + + def test_negative_max_retries_still_attempts_delivery_once(self) -> None: + stub = _PostV1Stub([_results_response({"u-1": "ok"})]) + + with mock.patch("posthog.capture_send._post_v1", stub): + _send_v1_batch( + "phc_key", "https://app.posthog.com", [_msg("u-1")], max_retries=-1 + ) + + self.assertEqual(len(stub.calls), 1) + self.assertEqual(stub.calls[0]["attempt"], 1) + + def test_small_retry_after_does_not_shorten_backoff(self) -> None: + # A Retry-After smaller than the configured backoff must not make the + # client retry earlier than its own schedule (Retry-After is a minimum). + # attempt_index=1 -> configured backoff 0.2s; Retry-After 0.1s is ignored. + stub = self._run( + [_msg("u-1")], + [ + _results_response({"u-1": "retry"}), + _results_response({"u-1": "retry"}, headers={"Retry-After": "0.1"}), + _results_response({"u-1": "ok"}), + ], + max_retries=3, + ) + self.assertEqual(len(stub.calls), 3) + # First backoff (attempt_index 0) waits 0.1s; second (attempt_index 1) + # keeps the 0.2s configured backoff rather than the smaller 0.1s header. + self.assertEqual([c.args[0] for c in self.sleep.call_args_list], [0.1, 0.2]) + + +class TestCaptureLossMessage(unittest.TestCase): + @parameterized.expand( + [ + ( + "partial_2xx", + CaptureError( + 200, + "2 event(s) not delivered", + endpoint=_CAPTURE_V1_PATH, + drops=[("u-drop", "llm_events_over_quota")], + retry_exhausted=["u-retry"], + event_results={ + "u-ok": CaptureEventResult("ok"), + "u-drop": CaptureEventResult("drop", "llm_events_over_quota"), + "u-retry": CaptureEventResult("retry", "not_persisted"), + }, + ), + 3, + "2 event(s) not persisted by /i/v1/analytics/events: 1 dropped, " + "1 out of retries (drop/llm_events_over_quota=1, retry/not_persisted=1)", + ), + ( + "duplicate_drop_counts_its_own_reason", + CaptureError( + 200, + "2 event(s) dropped by the server", + endpoint=_CAPTURE_V1_PATH, + drops=[ + ("u-a", "duplicate_event_uuid"), + ("u-drop", "llm_events_over_quota"), + ], + event_results={ + "u-a": CaptureEventResult("ok"), + "u-drop": CaptureEventResult("drop", "llm_events_over_quota"), + }, + ), + 3, + "2 event(s) not persisted by /i/v1/analytics/events: 2 dropped, " + "0 out of retries (drop/duplicate_event_uuid=1, drop/llm_events_over_quota=1)", + ), + ( + "request_failure_after_partial_success", + CaptureError( + 503, + "unavailable", + endpoint=_CAPTURE_AI_V1_PATH, + event_results={ + "u-ok": CaptureEventResult("warning"), + "u-retry": CaptureEventResult("retry"), + }, + ), + 2, + "1 event(s) not persisted by /i/v1/ai/events: CaptureError (status=503)", + ), + ( + "other_exception_uses_caller_endpoint", + ValueError("bad payload"), + 4, + "4 event(s) not persisted by /i/v1/analytics/events: ValueError", + ), + ] + ) + def test_message(self, _name, error, batch_size, expected) -> None: + self.assertEqual( + _capture_loss_message(error, batch_size, _CAPTURE_V1_PATH), expected + ) + + def test_hand_built_drops_get_named_fields(self) -> None: + error = CaptureError( + 200, "dropped", endpoint=_CAPTURE_V1_PATH, drops=[("u-drop", "invalid")] + ) + self.assertEqual( + (error.drops[0].uuid, error.drops[0].details), ("u-drop", "invalid") + ) + + +def _patch_no_jitter(test: unittest.TestCase) -> None: + # 0.5 draws a jitter factor of exactly 1.0. + patch = mock.patch.object(capture_send.random, "random", return_value=0.5) + patch.start() + test.addCleanup(patch.stop) + + +class TestBackoff(unittest.TestCase): + """Directly exercises ``_backoff``'s Retry-After-as-minimum + cap policy.""" + + def setUp(self) -> None: + _patch_no_jitter(self) + + @parameterized.expand( + [ + # (attempt_index, retry_after, expected sleep seconds) + ("first_no_header", 0, None, 0.1), + ("second_no_header", 1, None, 0.2), + ("exp_capped_at_30", 10, None, 30), + ("zero_header_uses_backoff", 0, 0, 0.1), + ("larger_header_wins", 0, 5.0, 5.0), + ("smaller_header_ignored", 3, 0.5, 0.8), # configured 0.8 > 0.5 + ("equal_header_and_backoff", 1, 0.2, 0.2), + ("header_at_ceiling", 0, 30.0, 30), + ("header_above_ceiling_clamped", 0, 120.0, _MAX_BACKOFF_SECONDS), + ("absurd_header_clamped", 0, 10**9, _MAX_BACKOFF_SECONDS), + ] + ) + def test_backoff(self, _name, attempt_index, retry_after, expected) -> None: + with mock.patch("posthog.capture_send.time.sleep") as sleep: + _backoff(attempt_index, retry_after) + sleep.assert_called_once() + self.assertAlmostEqual(sleep.call_args.args[0], expected) + + @parameterized.expand( + [ + # (draw, attempt_index, retry_after, expected sleep seconds) + ("lowest_draw_shortens_by_a_quarter", 0.0, 1, None, 0.15), + ("highest_draw_lengthens_by_a_quarter", 1.0, 1, None, 0.25), + ("jittered_wait_still_capped", 1.0, 10, None, _MAX_BACKOFF_SECONDS), + ("jitter_never_shortens_retry_after", 0.0, 1, 0.2, 0.2), + ("jitter_can_lengthen_past_retry_after", 1.0, 1, 0.2, 0.25), + ] + ) + def test_jitter(self, _name, draw, attempt_index, retry_after, expected) -> None: + with ( + mock.patch.object(capture_send.random, "random", return_value=draw), + mock.patch("posthog.capture_send.time.sleep") as sleep, + ): + _backoff(attempt_index, retry_after) + self.assertAlmostEqual(sleep.call_args.args[0], expected) diff --git a/posthog/test/test_capture_v1.py b/posthog/test/test_capture_v1.py deleted file mode 100644 index 56c05af36..000000000 --- a/posthog/test/test_capture_v1.py +++ /dev/null @@ -1,771 +0,0 @@ -import json -import unittest -import zlib -from datetime import datetime, timedelta, timezone -from unittest import mock - -import zstandard - -from parameterized import parameterized - -from posthog.capture_compression import CaptureCompression -from posthog.capture_v1 import ( - _CAPTURE_V1_PATH, - _HEADER_ATTEMPT, - _HEADER_REQUEST_ID, - _HEADER_REQUEST_TIMESTAMP, - _HEADER_SDK_INFO, - _MAX_BACKOFF_SECONDS, - CaptureV1Error, - _build_v1_batch_body, - _parse_v1_response, - _post_v1, - _send_v1_batch, - _to_v1_event, - _backoff, - _coerce_bool, - _coerce_str, -) -from posthog.request import USER_AGENT - - -class _FakeResponse: - """Minimal stand-in for ``requests.Response`` for transport tests.""" - - def __init__( - self, status_code, *, json_body=None, headers=None, text="", raise_json=False - ): - self.status_code = status_code - self.headers = headers or {} - self.text = text - self._json_body = json_body - self._raise_json = raise_json - - def json(self): - if self._raise_json: - raise ValueError("no json") - return self._json_body - - -class _RecordingSession: - """Captures the args of a single ``.post`` and returns a canned response.""" - - def __init__(self, response): - self._response = response - self.calls = [] - - def post(self, url, data=None, headers=None, timeout=None): - self.calls.append( - {"url": url, "data": data, "headers": headers, "timeout": timeout} - ) - return self._response - - -class _PostV1Stub: - """Drop-in for ``_post_v1`` that records calls and replays canned outcomes. - - Each item in ``outcomes`` is either a ``_FakeResponse`` to return or an - ``Exception`` instance to raise (simulating a transport failure). - """ - - def __init__(self, outcomes): - self._outcomes = list(outcomes) - self.calls = [] - - def __call__( - self, - api_key, - host, - batch_body, - *, - attempt, - request_id, - compression=CaptureCompression.NONE, - timeout=15, - sdk_info=USER_AGENT, - session=None, - ): - self.calls.append( - { - "attempt": attempt, - "request_id": request_id, - "compression": compression, - "sdk_info": sdk_info, - "created_at": batch_body["created_at"], - "uuids": [e["uuid"] for e in batch_body["batch"]], - } - ) - outcome = self._outcomes[len(self.calls) - 1] - if isinstance(outcome, Exception): - raise outcome - return outcome - - -def _msg(uuid, event="e", **overrides): - msg = { - "event": event, - "uuid": uuid, - "distinct_id": "user-1", - "timestamp": "2026-06-27T12:00:00+00:00", - "type": "capture", - "properties": {}, - } - msg.update(overrides) - return msg - - -def _results_response(directives, headers=None): - """200 response whose ``results`` map tags each uuid. - - ``directives`` maps uuid -> ``"ok"`` (or any result string) or a - ``(result, details)`` tuple. - """ - results = {} - for uid, spec in directives.items(): - result, details = spec if isinstance(spec, tuple) else (spec, None) - results[uid] = {"result": result, "details": details} - return _FakeResponse(200, json_body={"results": results}, headers=headers) - - -def _legacy_msg(event="my_event", properties=None, **overrides) -> dict: - """Minimal legacy-shaped message as it looks coming off the queue.""" - msg = { - "event": event, - "uuid": "0190000000007000800000000000000a", - "distinct_id": "user-1", - "timestamp": "2026-06-27T12:00:00+00:00", - "type": "capture", - "properties": {"$lib": "posthog-python", "$lib_version": "9.9.9"}, - } - if properties is not None: - msg["properties"] = properties - msg.update(overrides) - return msg - - -class TestCoercion(unittest.TestCase): - @parameterized.expand( - [ - ("bool_true", True, True), - ("bool_false", False, False), - ("str_true", "true", True), - ("str_true_upper", "TRUE", True), - ("str_true_padded", " true ", True), - ("str_one", "1", True), - ("str_false", "false", False), - ("str_zero", "0", False), - ("int_nonzero", 5, True), - ("int_zero", 0, False), - ("float_nonzero", 1.5, True), - ("float_zero", 0.0, False), - ("neg_int", -1, True), - ("str_yes_uncoercible", "yes", None), - ("str_empty_uncoercible", "", None), - ("none_uncoercible", None, None), - ("dict_uncoercible", {"a": 1}, None), - ] - ) - def test_coerce_bool(self, _name, value, expected) -> None: - self.assertIs(_coerce_bool(value), expected) - - @parameterized.expand( - [ - ("str", "tour-1", "tour-1"), - ("empty_str", "", ""), - ("int", 123, None), - ("bool", True, None), - ("none", None, None), - ] - ) - def test_coerce_str(self, _name, value, expected) -> None: - self.assertEqual(_coerce_str(value), expected) - - -class TestToV1Event(unittest.TestCase): - def test_required_fields_preserved(self) -> None: - event = _to_v1_event(_legacy_msg(event="signed_up")) - self.assertEqual(event["event"], "signed_up") - self.assertEqual(event["uuid"], "0190000000007000800000000000000a") - self.assertEqual(event["distinct_id"], "user-1") - self.assertEqual(event["timestamp"], "2026-06-27T12:00:00+00:00") - - def test_strips_lib_and_lib_version(self) -> None: - event = _to_v1_event(_legacy_msg()) - self.assertNotIn("$lib", event["properties"]) - self.assertNotIn("$lib_version", event["properties"]) - - def test_options_empty_dict_when_no_sentinels(self) -> None: - event = _to_v1_event(_legacy_msg(properties={"plain": "value"})) - self.assertEqual(event["options"], {}) - self.assertEqual(event["properties"], {"plain": "value"}) - - def test_does_not_leak_non_wire_top_level_keys(self) -> None: - event = _to_v1_event(_legacy_msg()) - # `type` is legacy-only; the v1 event carries only documented fields. - self.assertEqual( - set(event), - {"event", "uuid", "distinct_id", "timestamp", "options", "properties"}, - ) - - def test_does_not_mutate_input(self) -> None: - msg = _legacy_msg( - properties={"$cookieless_mode": True, "$session_id": "s-1"}, - **{"$set": {"name": "Max"}}, - ) - original_properties = dict(msg["properties"]) - _to_v1_event(msg) - self.assertEqual(msg["properties"], original_properties) - self.assertIn("$set", msg) # top-level $set untouched on the original - - @parameterized.expand( - [ - ("cookieless_mode", "$cookieless_mode", "cookieless_mode", True, True), - ( - "ignore_sent_at_rename", - "$ignore_sent_at", - "disable_skew_correction", - "true", - True, - ), - ( - "process_person_profile", - "$process_person_profile", - "process_person_profile", - "false", - False, - ), - ( - "product_tour_id", - "$product_tour_id", - "product_tour_id", - "tour-7", - "tour-7", - ), - ] - ) - def test_option_sentinels_lifted_renamed_and_coerced( - self, _name, prop_key, wire_key, raw, expected - ) -> None: - event = _to_v1_event(_legacy_msg(properties={prop_key: raw})) - self.assertEqual(event["options"], {wire_key: expected}) - self.assertNotIn(prop_key, event["properties"]) - - @parameterized.expand( - [ - ("bad_bool", "$cookieless_mode", "maybe"), - ("bad_tour_id_int", "$product_tour_id", 123), - ] - ) - def test_option_sentinel_removed_but_omitted_on_bad_coercion( - self, _name, prop_key, raw - ) -> None: - event = _to_v1_event(_legacy_msg(properties={prop_key: raw})) - # Removed from properties (sentinels must never reach v1 props) but not - # emitted as an option, so a wrong type cannot 400 the whole batch. - self.assertNotIn(prop_key, event["properties"]) - self.assertEqual(event["options"], {}) - - @parameterized.expand( - [ - ("session_id", "$session_id", "session_id", "s-123"), - ("window_id", "$window_id", "window_id", "w-456"), - ] - ) - def test_top_level_string_sentinels(self, _name, prop_key, field_name, raw) -> None: - event = _to_v1_event(_legacy_msg(properties={prop_key: raw})) - self.assertEqual(event[field_name], raw) - self.assertNotIn(prop_key, event["properties"]) - - def test_top_level_sentinel_omitted_but_removed_when_not_string(self) -> None: - event = _to_v1_event(_legacy_msg(properties={"$session_id": 42})) - self.assertNotIn("session_id", event) - self.assertNotIn("$session_id", event["properties"]) - - def test_all_sentinels_together(self) -> None: - event = _to_v1_event( - _legacy_msg( - properties={ - "$cookieless_mode": True, - "$ignore_sent_at": "1", - "$product_tour_id": "tour-x", - "$process_person_profile": 0, - "$session_id": "s-1", - "$window_id": "w-1", - "$geoip_disable": True, - "custom": "keep", - } - ) - ) - self.assertEqual( - event["options"], - { - "cookieless_mode": True, - "disable_skew_correction": True, - "product_tour_id": "tour-x", - "process_person_profile": False, - }, - ) - self.assertEqual(event["session_id"], "s-1") - self.assertEqual(event["window_id"], "w-1") - # Non-sentinel props (including $geoip_disable) are left intact. - self.assertEqual( - event["properties"], {"$geoip_disable": True, "custom": "keep"} - ) - - @parameterized.expand([("set", "$set"), ("set_once", "$set_once")]) - def test_top_level_set_relocated_into_properties(self, _name, key) -> None: - msg = _legacy_msg(properties={}, **{key: {"email": "a@b.com"}}) - event = _to_v1_event(msg) - self.assertEqual(event["properties"][key], {"email": "a@b.com"}) - self.assertNotIn(key, event) # not a top-level v1 field - - def test_top_level_set_merges_with_existing_properties_set(self) -> None: - # properties wins on key collision. - msg = _legacy_msg( - properties={"$set": {"a": "from_props", "b": "props_only"}}, - **{"$set": {"a": "from_top", "c": "top_only"}}, - ) - event = _to_v1_event(msg) - self.assertEqual( - event["properties"]["$set"], - {"a": "from_props", "b": "props_only", "c": "top_only"}, - ) - - def test_groups_left_in_properties(self) -> None: - event = _to_v1_event(_legacy_msg(properties={"$groups": {"company": "ph"}})) - self.assertEqual(event["properties"]["$groups"], {"company": "ph"}) - - def test_timestamp_naive_datetime_made_tz_aware(self) -> None: - event = _to_v1_event(_legacy_msg(timestamp=datetime(2026, 6, 27, 12, 0, 0))) - parsed = datetime.fromisoformat(event["timestamp"]) - self.assertIsNotNone(parsed.tzinfo) - - def test_timestamp_aware_datetime_converted_to_exact_utc_instant(self) -> None: - event = _to_v1_event( - _legacy_msg( - timestamp=datetime( - 2026, - 6, - 27, - 17, - 45, - tzinfo=timezone(timedelta(hours=5, minutes=45)), - ) - ) - ) - self.assertEqual(event["timestamp"], "2026-06-27T12:00:00+00:00") - - def test_timestamp_parseable_string_converted_to_exact_utc_instant(self) -> None: - event = _to_v1_event(_legacy_msg(timestamp="2026-06-27T17:45:00+05:45")) - self.assertEqual(event["timestamp"], "2026-06-27T12:00:00+00:00") - - def test_timestamp_none_defaults_to_utc_now(self) -> None: - event = _to_v1_event(_legacy_msg(timestamp=None)) - parsed = datetime.fromisoformat(event["timestamp"]) - self.assertEqual(parsed.tzinfo, timezone.utc) - - -class TestBuildV1BatchBody(unittest.TestCase): - def test_envelope_shape_and_no_legacy_fields(self) -> None: - events = [{"event": "e"}] - body = _build_v1_batch_body(events) - self.assertEqual(body["batch"], events) - self.assertNotIn("api_key", body) - self.assertNotIn("sent_at", body) - - def test_created_at_is_tz_aware_rfc3339(self) -> None: - body = _build_v1_batch_body([]) - parsed = datetime.fromisoformat(body["created_at"]) - self.assertIsNotNone(parsed.tzinfo) - - def test_created_at_passthrough_used_verbatim(self) -> None: - # _send_v1_batch hoists created_at and passes it in so it stays stable - # across retry attempts. - body = _build_v1_batch_body([], created_at="2026-06-27T12:00:00+00:00") - self.assertEqual(body["created_at"], "2026-06-27T12:00:00+00:00") - - def test_historical_migration_omitted_when_false(self) -> None: - self.assertNotIn("historical_migration", _build_v1_batch_body([])) - - def test_historical_migration_present_when_true(self) -> None: - body = _build_v1_batch_body([], historical_migration=True) - self.assertIs(body["historical_migration"], True) - - -class TestPostV1(unittest.TestCase): - def _post(self, response, **kwargs): - session = _RecordingSession(response) - body = _build_v1_batch_body([_to_v1_event(_msg("u-1"))]) - _post_v1( - "phc_key", - "https://app.posthog.com/", - body, - attempt=2, - request_id="req-123", - session=session, - **kwargs, - ) - return session.calls[0] - - def test_url_uses_v1_path_and_trims_host(self) -> None: - call = self._post(_results_response({})) - self.assertEqual(call["url"], "https://app.posthog.com" + _CAPTURE_V1_PATH) - - def test_required_headers_present(self) -> None: - headers = self._post(_results_response({}))["headers"] - self.assertEqual(headers["Authorization"], "Bearer phc_key") - self.assertEqual(headers[_HEADER_ATTEMPT], "2") - self.assertEqual(headers[_HEADER_REQUEST_ID], "req-123") - self.assertTrue(headers[_HEADER_SDK_INFO].startswith("posthog-python/")) - self.assertEqual(headers["Content-Type"], "application/json") - request_timestamp = datetime.fromisoformat(headers[_HEADER_REQUEST_TIMESTAMP]) - self.assertEqual(request_timestamp.utcoffset(), timedelta(0)) - - def test_custom_sdk_info_headers(self) -> None: - headers = self._post( - _results_response({}), sdk_info="posthog-python-mcp/0.3.0" - )["headers"] - self.assertEqual(headers[_HEADER_SDK_INFO], "posthog-python-mcp/0.3.0") - self.assertEqual(headers["User-Agent"], "posthog-python-mcp/0.3.0") - - def test_no_api_key_in_body(self) -> None: - # v1 authenticates via the Bearer header; the key must not leak into the body. - data = self._post(_results_response({}))["data"] - self.assertNotIn("phc_key", data) - self.assertNotIn("api_key", json.loads(data)) - - def test_uncompressed_body_is_json_str_without_encoding_header(self) -> None: - call = self._post(_results_response({}), compression=CaptureCompression.NONE) - self.assertIsInstance(call["data"], str) - self.assertNotIn("Content-Encoding", call["headers"]) - - def test_gzip_sets_encoding_header_and_compresses_body(self) -> None: - call = self._post(_results_response({}), compression=CaptureCompression.GZIP) - self.assertEqual(call["headers"]["Content-Encoding"], "gzip") - self.assertIsInstance(call["data"], bytes) - self.assertEqual(call["data"][:2], b"\x1f\x8b") # gzip magic - - def test_deflate_sets_encoding_header_and_zlib_wraps_body(self) -> None: - # Must be zlib-wrapped (RFC 1950, 0x78 prefix), matching posthog-go / - # posthog-rs, so the server routes Content-Encoding: deflate to its zlib - # decoder rather than treating it as raw deflate. - call = self._post(_results_response({}), compression=CaptureCompression.DEFLATE) - self.assertEqual(call["headers"]["Content-Encoding"], "deflate") - self.assertIsInstance(call["data"], bytes) - self.assertEqual(call["data"][0], 0x78) # zlib header - roundtripped = zlib.decompress(call["data"]).decode("utf-8") - self.assertNotIn("api_key", json.loads(roundtripped)) - - def test_zstd_sets_encoding_header_and_emits_standard_frame(self) -> None: - call = self._post(_results_response({}), compression=CaptureCompression.ZSTD) - self.assertEqual(call["headers"]["Content-Encoding"], "zstd") - self.assertIsInstance(call["data"], bytes) - self.assertEqual(call["data"][:4], b"\x28\xb5\x2f\xfd") # zstd frame magic - roundtripped = zstandard.ZstdDecompressor().decompress(call["data"]) - body = json.loads(roundtripped.decode("utf-8")) - self.assertNotIn("api_key", body) - self.assertEqual(len(body["batch"]), 1) - - def test_zstd_without_package_raises_actionable_error(self) -> None: - with mock.patch("posthog.capture_v1._zstandard", None): - with self.assertRaises(ValueError) as ctx: - self._post(_results_response({}), compression=CaptureCompression.ZSTD) - self.assertIn("posthog[zstd]", str(ctx.exception)) - - -class TestParseV1Response(unittest.TestCase): - def test_success_parses_results_with_details(self) -> None: - res = _FakeResponse( - 200, - json_body={"results": {"u-1": {"result": "drop", "details": "spam"}}}, - ) - parsed = _parse_v1_response(res) - self.assertTrue(parsed.is_success) - self.assertEqual(parsed.results["u-1"].result, "drop") - self.assertEqual(parsed.results["u-1"].details, "spam") - - @parameterized.expand( - [ - ("unparseable_body", _FakeResponse(200, raise_json=True)), - ("missing_results_key", _FakeResponse(200, json_body={"foo": 1})), - ] - ) - def test_success_with_bad_body_is_malformed(self, _name, res) -> None: - parsed = _parse_v1_response(res) - self.assertTrue(parsed.is_success) - self.assertTrue(parsed.malformed) - - @parameterized.expand( - [ - ("error_description", {"error_description": "bad batch"}, "bad batch"), - ("error", {"error": "validation_error"}, "validation_error"), - ("detail", {"detail": "nope"}, "nope"), - ] - ) - def test_error_message_extracted_from_body(self, _name, body, expected) -> None: - parsed = _parse_v1_response(_FakeResponse(400, json_body=body)) - self.assertFalse(parsed.is_success) - self.assertEqual(parsed.error_message, expected) - - def test_error_message_falls_back_to_text(self) -> None: - parsed = _parse_v1_response(_FakeResponse(400, raise_json=True, text="boom")) - self.assertEqual(parsed.error_message, "boom") - - @parameterized.expand([("numeric", "2", 2.0), ("absent", None, None)]) - def test_retry_after_header(self, _name, header_value, expected) -> None: - headers = {"Retry-After": header_value} if header_value is not None else {} - parsed = _parse_v1_response(_FakeResponse(503, headers=headers)) - self.assertEqual(parsed.retry_after, expected) - - -class TestSendV1Batch(unittest.TestCase): - """Drives ``_send_v1_batch`` with a stubbed ``_post_v1`` and no real sleeps.""" - - def setUp(self) -> None: - sleep_patch = mock.patch("posthog.capture_v1.time.sleep") - self.sleep = sleep_patch.start() - self.addCleanup(sleep_patch.stop) - - def _run(self, batch, outcomes, **kwargs): - stub = _PostV1Stub(outcomes) - with mock.patch("posthog.capture_v1._post_v1", stub): - _send_v1_batch("phc_key", "https://app.posthog.com", batch, **kwargs) - return stub - - def _run_expecting_error(self, batch, outcomes, **kwargs): - stub = _PostV1Stub(outcomes) - with mock.patch("posthog.capture_v1._post_v1", stub): - with self.assertRaises(CaptureV1Error) as ctx: - _send_v1_batch("phc_key", "https://app.posthog.com", batch, **kwargs) - return stub, ctx.exception - - def test_all_ok_sends_once(self) -> None: - stub = self._run([_msg("u-1")], [_results_response({"u-1": "ok"})]) - self.assertEqual(len(stub.calls), 1) - self.sleep.assert_not_called() - - def test_custom_sdk_info_is_forwarded(self) -> None: - stub = self._run( - [_msg("u-1")], - [_results_response({"u-1": "ok"})], - sdk_info="posthog-python-mcp/0.3.0", - ) - self.assertEqual(stub.calls[0]["sdk_info"], "posthog-python-mcp/0.3.0") - - def test_absent_uuid_treated_as_accepted(self) -> None: - # Empty results map: the event is neither retried nor errored. - stub = self._run([_msg("u-1")], [_results_response({})]) - self.assertEqual(len(stub.calls), 1) - - def test_partial_retry_resends_only_retry_events(self) -> None: - batch = [_msg("u-ok"), _msg("u-retry")] - stub = self._run( - batch, - [ - _results_response({"u-ok": "ok", "u-retry": "retry"}), - _results_response({"u-retry": "ok"}), - ], - ) - self.assertEqual(len(stub.calls), 2) - self.assertEqual(stub.calls[0]["uuids"], ["u-ok", "u-retry"]) - # Second attempt carries only the event the server asked to retry. - self.assertEqual(stub.calls[1]["uuids"], ["u-retry"]) - - def test_request_id_and_created_at_stable_attempt_increments(self) -> None: - stub = self._run( - [_msg("u-1")], - [ - _results_response({"u-1": "retry"}), - _results_response({"u-1": "ok"}), - ], - ) - self.assertEqual(stub.calls[0]["request_id"], stub.calls[1]["request_id"]) - # created_at is hoisted once, so the envelope timestamp is identical - # across retry attempts (only the attempt header increments). - self.assertEqual(stub.calls[0]["created_at"], stub.calls[1]["created_at"]) - self.assertEqual([c["attempt"] for c in stub.calls], [1, 2]) - - def test_compression_forwarded_to_post_v1(self) -> None: - stub = self._run( - [_msg("u-1")], - [_results_response({"u-1": "ok"})], - compression=CaptureCompression.DEFLATE, - ) - self.assertEqual(stub.calls[0]["compression"], CaptureCompression.DEFLATE) - - def test_drop_on_2xx_surfaces_via_error(self) -> None: - # A server-chosen drop is terminal: even on an all-ok-otherwise 2xx with - # no retry events, the send raises so on_error sees the dropped uuid - # (matches posthog-go/posthog-rs — a 2xx is not full delivery). - batch = [_msg("u-ok"), _msg("u-drop")] - stub, exc = self._run_expecting_error( - batch, - [_results_response({"u-ok": "ok", "u-drop": ("drop", "invalid")})], - ) - self.assertEqual(len(stub.calls), 1) # terminal, not retried - self.assertEqual(exc.status, 200) - self.assertEqual(exc.drops, [("u-drop", "invalid")]) - self.assertEqual(exc.retry_exhausted, []) - - def test_all_ok_no_drops_does_not_raise(self) -> None: - # The success path is unchanged when the server drops nothing. - stub = self._run( - [_msg("u-1"), _msg("u-2")], - [_results_response({"u-1": "ok", "u-2": "warning"})], - ) - self.assertEqual(len(stub.calls), 1) - - def test_drop_accumulated_across_attempts_surfaces_on_later_success(self) -> None: - # Attempt 1 drops one event and retries another; attempt 2 clears the - # retry. The earlier drop must still surface — it is not lost when the - # outstanding retries succeed on a later 2xx. - batch = [_msg("u-drop"), _msg("u-retry")] - stub, exc = self._run_expecting_error( - batch, - [ - _results_response({"u-drop": ("drop", "billing"), "u-retry": "retry"}), - _results_response({"u-retry": "ok"}), - ], - ) - self.assertEqual(len(stub.calls), 2) - self.assertEqual(stub.calls[1]["uuids"], ["u-retry"]) # only retry resent - self.assertEqual(exc.drops, [("u-drop", "billing")]) - self.assertEqual(exc.retry_exhausted, []) - - def test_retry_exhausted_raises_with_uuids(self) -> None: - stub, exc = self._run_expecting_error( - [_msg("u-1")], - [_results_response({"u-1": "retry"}), _results_response({"u-1": "retry"})], - max_retries=1, - ) - self.assertEqual(len(stub.calls), 2) - self.assertEqual(exc.retry_exhausted, ["u-1"]) - self.assertEqual(exc.drops, []) - - def test_retry_exhausted_carries_earlier_drops(self) -> None: - # A drop seen on attempt 1 rides along on the retry-exhaustion error. - batch = [_msg("u-drop"), _msg("u-retry")] - stub, exc = self._run_expecting_error( - batch, - [ - _results_response({"u-drop": ("drop", "billing"), "u-retry": "retry"}), - _results_response({"u-retry": "retry"}), - ], - max_retries=1, - ) - self.assertEqual(len(stub.calls), 2) - self.assertEqual(exc.retry_exhausted, ["u-retry"]) - self.assertEqual(exc.drops, [("u-drop", "billing")]) - - def test_malformed_2xx_is_terminal(self) -> None: - stub, exc = self._run_expecting_error( - [_msg("u-1")], [_FakeResponse(200, raise_json=True)] - ) - self.assertEqual(len(stub.calls), 1) - self.assertEqual(exc.status, 200) - - @parameterized.expand([("bad_request", 400), ("billing_limit", 402)]) - def test_terminal_status_raises_immediately(self, _name, status) -> None: - stub, exc = self._run_expecting_error( - [_msg("u-1")], - [_FakeResponse(status, json_body={"error": "nope"})], - max_retries=2, - ) - self.assertEqual(len(stub.calls), 1) # not retried - self.assertEqual(exc.status, status) - - @parameterized.expand( - [("not_found", 404), ("rate_limited", 429), ("unavailable", 503)] - ) - def test_retryable_status_then_success(self, _name, status) -> None: - stub = self._run( - [_msg("u-1")], - [ - _FakeResponse(status, headers={"Retry-After": "2"}), - _results_response({"u-1": "ok"}), - ], - ) - self.assertEqual(len(stub.calls), 2) - self.sleep.assert_called_once_with(2.0) # honored Retry-After - - @parameterized.expand( - [("not_found", 404), ("rate_limited", 429), ("unavailable", 503)] - ) - def test_retryable_status_exhausted_raises(self, _name, status) -> None: - stub, exc = self._run_expecting_error( - [_msg("u-1")], [_FakeResponse(status), _FakeResponse(status)], max_retries=1 - ) - self.assertEqual(len(stub.calls), 2) - self.assertEqual(exc.status, status) - self.assertEqual(exc.attempts, 2) - # One 1s backoff between the two attempts, none after the final one. - self.assertEqual([c.args[0] for c in self.sleep.call_args_list], [1]) - - def test_transport_error_then_success(self) -> None: - stub = self._run( - [_msg("u-1")], - [ConnectionError("boom"), _results_response({"u-1": "ok"})], - ) - self.assertEqual(len(stub.calls), 2) - - def test_transport_error_exhausted_reraises_original(self) -> None: - stub = _PostV1Stub([ConnectionError("boom"), ConnectionError("boom")]) - with mock.patch("posthog.capture_v1._post_v1", stub): - with self.assertRaises(ConnectionError): - _send_v1_batch( - "phc_key", "https://app.posthog.com", [_msg("u-1")], max_retries=1 - ) - self.assertEqual(len(stub.calls), 2) - - def test_negative_max_retries_still_attempts_delivery_once(self) -> None: - stub = _PostV1Stub([_results_response({"u-1": "ok"})]) - - with mock.patch("posthog.capture_v1._post_v1", stub): - _send_v1_batch( - "phc_key", "https://app.posthog.com", [_msg("u-1")], max_retries=-1 - ) - - self.assertEqual(len(stub.calls), 1) - self.assertEqual(stub.calls[0]["attempt"], 1) - - def test_small_retry_after_does_not_shorten_backoff(self) -> None: - # A Retry-After smaller than the configured backoff must not make the - # client retry earlier than its own schedule (Retry-After is a minimum). - # attempt_index=1 -> configured backoff 2s; Retry-After 0.5s is ignored. - stub = self._run( - [_msg("u-1")], - [ - _results_response({"u-1": "retry"}), - _results_response({"u-1": "retry"}, headers={"Retry-After": "0.5"}), - _results_response({"u-1": "ok"}), - ], - max_retries=3, - ) - self.assertEqual(len(stub.calls), 3) - # First backoff (attempt_index 0) waits 1s; second (attempt_index 1) - # keeps the 2s configured backoff rather than the smaller 0.5s header. - self.assertEqual([c.args[0] for c in self.sleep.call_args_list], [1, 2]) - - -class TestBackoff(unittest.TestCase): - """Directly exercises ``_backoff``'s Retry-After-as-minimum + cap policy.""" - - @parameterized.expand( - [ - # (attempt_index, retry_after, expected sleep seconds) - ("first_no_header", 0, None, 1), - ("second_no_header", 1, None, 2), - ("exp_capped_at_30", 10, None, 30), - ("zero_header_uses_backoff", 0, 0, 1), - ("larger_header_wins", 0, 5.0, 5.0), - ("smaller_header_ignored", 3, 2.0, 8), # configured 8 > 2.0 - ("equal_header_and_backoff", 0, 1.0, 1), - ("header_at_ceiling", 0, 30.0, 30), - ("header_above_ceiling_clamped", 0, 120.0, _MAX_BACKOFF_SECONDS), - ("absurd_header_clamped", 0, 10**9, _MAX_BACKOFF_SECONDS), - ] - ) - def test_backoff(self, _name, attempt_index, retry_after, expected) -> None: - with mock.patch("posthog.capture_v1.time.sleep") as sleep: - _backoff(attempt_index, retry_after) - sleep.assert_called_once_with(expected) diff --git a/posthog/test/test_client.py b/posthog/test/test_client.py index aee8342ab..5381af3db 100644 --- a/posthog/test/test_client.py +++ b/posthog/test/test_client.py @@ -18,8 +18,15 @@ import pytest from posthog.capture_compression import CaptureCompression +from posthog.capture_send import _CAPTURE_AI_V1_PATH, _CAPTURE_V1_PATH from posthog.client import Client -from posthog.contexts import get_context_session_id, new_context, set_context_session +from posthog.contexts import ( + get_context_session_id, + identify_context, + new_context, + set_context_option, + set_context_session, +) from posthog.request import APIError, GetResponse from posthog.test.logging_helpers import capture_message_only_logs from posthog.test.test_utils import FAKE_TEST_API_KEY @@ -27,6 +34,7 @@ from posthog.utils import RedisFlagCache from posthog.version import VERSION from posthog.contexts import tag +from posthog.test.capture_helpers import patch_capture_send, sent_batch, sent_events # Legacy single-flag behavior remains covered here; warning emission itself is @@ -54,8 +62,8 @@ class TestClient(unittest.TestCase): @classmethod def setUpClass(cls): # This ensures no real HTTP POST requests are made - cls.client_post_patcher = mock.patch("posthog.client.batch_post") - cls.consumer_post_patcher = mock.patch("posthog.consumer.batch_post") + cls.client_post_patcher = patch_capture_send("client") + cls.consumer_post_patcher = patch_capture_send("consumer") cls.client_post_patcher.start() cls.consumer_post_patcher.start() @@ -78,23 +86,32 @@ def test_requires_api_key(self): @parameterized.expand( [ - ("valid_key", " \nphc_validkey\t ", "phc_validkey", False, False), - ("whitespace_only", " \n\t ", "", True, True), - ("empty_string", "", "", True, True), + ("valid_key", " \nphc_validkey\t ", "phc_validkey", False, None), + ("whitespace_only", " \n\t ", "", True, "api_key is empty"), + ("empty_string", "", "", True, "api_key is empty"), + ( + "personal_api_key", + " phx_secret ", + "phx_secret", + True, + "personal API key", + ), ] ) def test_trims_api_key_whitespace( - self, _, raw_api_key, expected_api_key, expected_disabled, expect_error_log + self, _, raw_api_key, expected_api_key, expected_disabled, expected_error ): with mock.patch.object(Client.log, "error") as mock_error: client = Client(raw_api_key, send=False) self.assertEqual(client.api_key, expected_api_key) self.assertEqual(client.disabled, expected_disabled) - if expect_error_log: - mock_error.assert_called_once_with( - "api_key is empty after trimming whitespace; check your project API key" - ) + if expected_error: + mock_error.assert_called_once() + message = " ".join(str(arg) for arg in mock_error.call_args.args) + self.assertIn(expected_error, message) + self.assertNotIn("secret", message) + self.assertIsNone(client.capture("event", distinct_id="user")) else: mock_error.assert_not_called() @@ -293,7 +310,7 @@ def test_empty_flush(self): self.client.flush() def test_empty_flush_does_not_drain_a_later_event(self): - with mock.patch("posthog.consumer.batch_post") as mock_post: + with patch_capture_send("consumer") as mock_post: client = Client(FAKE_TEST_API_KEY, flush_at=100, flush_interval=0.5) client.flush() @@ -322,7 +339,7 @@ def test_flush_timeout_returns_when_queue_does_not_drain(self): def test_flush_does_not_wait_for_flush_interval(self): # flush() must attempt delivery now rather than letting the consumer sit # on a below-flush_at batch until flush_interval elapses. - with mock.patch("posthog.consumer.batch_post") as mock_post: + with patch_capture_send("consumer") as mock_post: client = Client(FAKE_TEST_API_KEY, flush_interval=30) client.capture("event", distinct_id="distinct_id") @@ -336,7 +353,7 @@ def test_flush_does_not_wait_for_flush_interval(self): def test_flush_delivers_when_flush_interval_exceeds_the_flush_timeout(self): # Waiting out flush_interval meant a flush_interval longer than the # flush timeout delivered nothing at all. - with mock.patch("posthog.consumer.batch_post") as mock_post: + with patch_capture_send("consumer") as mock_post: client = Client(FAKE_TEST_API_KEY, flush_interval=30) client.capture("event", distinct_id="distinct_id") @@ -347,7 +364,7 @@ def test_flush_delivers_when_flush_interval_exceeds_the_flush_timeout(self): def test_flush_keeps_batches_whole(self): # Draining early must not turn a full queue into one request per event. - with mock.patch("posthog.consumer.batch_post") as mock_post: + with patch_capture_send("consumer") as mock_post: client = Client(FAKE_TEST_API_KEY, flush_at=10, flush_interval=30) for _ in range(30): client.capture("event", distinct_id="distinct_id") @@ -356,7 +373,8 @@ def test_flush_keeps_batches_whole(self): self.assertTrue(client.queue.empty()) batch_sizes = [ - len(call.kwargs["batch"]) for call in mock_post.call_args_list + len(sent_batch(mock_post, index)) + for index in range(mock_post.call_count) ] self.assertEqual(sum(batch_sizes), 30) self.assertLessEqual(len(batch_sizes), 5) @@ -379,7 +397,7 @@ def test_flush_logs_and_returns_on_unexpected_error(self): client.queue.task_done() def test_basic_capture(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) msg_uuid = client.capture("python test event", distinct_id="distinct_id") self.assertIsNotNone(msg_uuid) @@ -387,7 +405,7 @@ def test_basic_capture(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "python test event") @@ -404,7 +422,7 @@ def test_basic_capture(self): assert msg["properties"]["$os_version"] == mock.ANY def test_capture_omits_is_server_when_disabled(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -414,26 +432,12 @@ def test_capture_omits_is_server_when_disabled(self): client.capture("python test event", distinct_id="distinct_id") self.assertFalse(self.failed) - msg = mock_post.call_args[1]["batch"][0] + msg = sent_batch(mock_post)[0] self.assertEqual(msg["properties"]["$lib"], "posthog-python") self.assertNotIn("$is_server", msg["properties"]) - def test_is_server_not_overridden_by_super_properties(self): - with mock.patch("posthog.client.batch_post") as mock_post: - client = Client( - FAKE_TEST_API_KEY, - on_error=self.set_fail, - sync_mode=True, - super_properties={"$is_server": False}, - ) - client.capture("python test event", distinct_id="distinct_id") - self.assertFalse(self.failed) - - msg = mock_post.call_args[1]["batch"][0] - self.assertEqual(msg["properties"]["$is_server"], True) - def test_basic_capture_with_uuid(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) uuid = str(uuid4()) msg_uuid = client.capture( @@ -444,7 +448,7 @@ def test_basic_capture_with_uuid(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "python test event") @@ -455,7 +459,7 @@ def test_basic_capture_with_uuid(self): self.assertEqual(msg["properties"]["$lib_version"], VERSION) def test_basic_capture_with_uuid_object(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) uuid = UUID("00000000-0000-4000-8000-000000000002") msg_uuid = client.capture( @@ -465,54 +469,77 @@ def test_basic_capture_with_uuid_object(self): self.assertFalse(self.failed) mock_post.assert_called_once() - msg = mock_post.call_args[1]["batch"][0] + msg = sent_batch(mock_post)[0] self.assertEqual(msg["uuid"], str(uuid)) @parameterized.expand( [ - ("empty string", ""), - ("invalid string", "not-a-uuid"), + ("uppercase", "0190A3B4-C5D6-7E8F-9A0B-1C2D3E4F5A6B"), + ("no hyphens", "0190a3b4c5d67e8f9a0b1c2d3e4f5a6b"), + ("braced", "{0190a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b}"), + ] + ) + def test_capture_sends_and_returns_canonical_uuid(self, _name, supplied): + with patch_capture_send("client") as mock_post: + client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) + msg_uuid = client.capture( + "python test event", distinct_id="distinct_id", uuid=supplied + ) + + canonical = "0190a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b" + self.assertEqual(msg_uuid, canonical) + self.assertEqual(sent_batch(mock_post)[0]["uuid"], canonical) + + @parameterized.expand( + [ + ("invalid string", "not-a-uuid-secret-1"), ("short string", "1234"), ("integer", 123), ] ) - def test_capture_with_invalid_uuid_logs_and_falls_back_to_generated_uuid( + def test_capture_with_invalid_uuid_warns_and_falls_back_to_generated_uuid( self, _name, invalid_uuid ): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) - with self.assertLogs("posthog", level="ERROR") as logs: + with self.assertLogs("posthog", level="WARNING") as logs: msg_uuid = client.capture( "python test event", distinct_id="distinct_id", uuid=invalid_uuid ) self.assertIsNotNone(msg_uuid) - UUID(msg_uuid) + self.assertEqual(UUID(msg_uuid).version, 7) mock_post.assert_called_once() - msg = mock_post.call_args[1]["batch"][0] + msg = sent_batch(mock_post)[0] self.assertEqual(msg["uuid"], msg_uuid) self.assertNotEqual(msg["uuid"], str(invalid_uuid)) - self.assertTrue( - any( - f"Invalid event uuid {invalid_uuid!r}" in message - and "Expected a valid UUID string or uuid.UUID instance" in message - and "Falling back to a generated UUID" in message - for message in logs.output + uuid_warnings = [r for r in logs.records if "Event uuid" in r.getMessage()] + self.assertEqual(len(uuid_warnings), 1) + self.assertEqual(uuid_warnings[0].levelname, "WARNING") + self.assertNotIn(str(invalid_uuid), uuid_warnings[0].getMessage()) + + def test_capture_with_empty_uuid_generates_one_without_logging(self): + with patch_capture_send("client") as mock_post: + client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) + with self.assertNoLogs("posthog", level="WARNING"): + msg_uuid = client.capture( + "python test event", distinct_id="distinct_id", uuid="" ) - ) + + self.assertEqual(UUID(msg_uuid).version, 7) + self.assertEqual(sent_batch(mock_post)[0]["uuid"], msg_uuid) @parameterized.expand( [ - ("empty string", ""), ("invalid string", "not-a-uuid"), ("short string", "1234"), ("integer", 123), ] ) def test_capture_with_invalid_uuid_falls_back_in_debug(self, _name, invalid_uuid): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, debug=True, sync_mode=True) - with self.assertLogs("posthog", level="ERROR"): + with self.assertLogs("posthog", level="WARNING"): msg_uuid = client.capture( "python test event", distinct_id="distinct_id", uuid=invalid_uuid ) @@ -522,7 +549,7 @@ def test_capture_with_invalid_uuid_falls_back_in_debug(self, _name, invalid_uuid mock_post.assert_called_once() def test_basic_capture_with_project_api_key(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( project_api_key=FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -535,7 +562,7 @@ def test_basic_capture_with_project_api_key(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "python test event") @@ -545,7 +572,7 @@ def test_basic_capture_with_project_api_key(self): self.assertEqual(msg["properties"]["$lib_version"], VERSION) def test_basic_super_properties(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, super_properties={"source": "repo-name"}, @@ -557,7 +584,7 @@ def test_basic_super_properties(self): # Check the enqueued message mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "python test event") @@ -574,44 +601,47 @@ def test_basic_capture_exception(self): self.assertEqual(capture_call[0][0], "$exception") self.assertEqual(capture_call[1]["distinct_id"], "distinct_id") - def test_reserved_exception_property_overrides_are_deprecated(self): - custom_exception_list = [{"type": "CustomError", "value": "custom"}] + def test_capture_exception_ignores_reserved_properties(self): properties = { - "$exception_list": custom_exception_list, + "$exception_list": [{"type": "CustomError", "value": "custom"}], "$exception_level": "warning", "$exception_source": "custom.source", - "$exception_issue_id": "legacy-issue-id", + "$exception_issue_id": "custom-issue-id", + "plan": "pro", } - with ( - mock.patch.object(Client, "capture", return_value=None) as patch_capture, - self.assertWarnsRegex( - DeprecationWarning, - "Reserved exception properties.*next major version", - ), - ): + with mock.patch.object(Client, "capture", return_value=None) as patch_capture: self.client.capture_exception( Exception("test exception"), properties=properties ) captured_properties = patch_capture.call_args.kwargs["properties"] - self.assertIs(captured_properties["$exception_list"], custom_exception_list) - self.assertEqual(captured_properties["$exception_level"], "warning") - self.assertEqual(captured_properties["$exception_source"], "custom.source") - self.assertEqual(captured_properties["$exception_issue_id"], "legacy-issue-id") + self.assertEqual(captured_properties["$exception_list"][0]["type"], "Exception") + self.assertEqual(captured_properties["$exception_level"], "error") + self.assertNotIn("$exception_source", captured_properties) + self.assertNotIn("$exception_issue_id", captured_properties) + self.assertEqual(captured_properties["plan"], "pro") - def test_reserved_exception_property_warning_cannot_drop_the_event(self): - with ( - mock.patch.object(Client, "capture", return_value=None) as patch_capture, - warnings.catch_warnings(), - ): - warnings.simplefilter("error", DeprecationWarning) + @parameterized.expand( + [ + ("default", None, None, "error"), + ("caller_level", None, "warning", "warning"), + ("alias", None, "WARN", "warning"), + ("unknown_level", None, "loud", "error"), + ("integration_level_wins", "fatal", "warning", "fatal"), + ] + ) + def test_capture_exception_level(self, _name, integration_level, level, expected): + capture_metadata = {"level": integration_level} if integration_level else {} + with mock.patch.object(Client, "capture", return_value=None) as patch_capture: self.client.capture_exception( Exception("test exception"), - properties={"$exception_level": "warning"}, + level=level, + _capture_metadata=capture_metadata, ) - patch_capture.assert_called_once() + captured_properties = patch_capture.call_args.kwargs["properties"] + self.assertEqual(captured_properties["$exception_level"], expected) @parameterized.expand( [ @@ -651,13 +681,13 @@ def test_capture_exception_uses_current_otel_span_context( ) with ( - mock.patch("posthog.client.batch_post") as mock_post, + patch_capture_send("client") as mock_post, use_span(NonRecordingSpan(span_context)), ): client = Client(FAKE_TEST_API_KEY, sync_mode=True) client.capture_exception(Exception("test exception"), properties=properties) - event = mock_post.call_args.kwargs["batch"][0] + event = sent_batch(mock_post)[0] if expected_trace_id is None: self.assertNotIn("$trace_id", event["properties"]) self.assertNotIn("$span_id", event["properties"]) @@ -725,7 +755,7 @@ def test_capture_uses_current_otel_span_context_when_enabled( ) with ( - mock.patch("posthog.client.batch_post") as mock_post, + patch_capture_send("client") as mock_post, use_span(NonRecordingSpan(span_context)), ): client = Client( @@ -734,7 +764,7 @@ def test_capture_uses_current_otel_span_context_when_enabled( capture = getattr(client, entrypoint) capture("$ai_event", distinct_id="distinct_id", properties=properties) - event = mock_post.call_args.kwargs["batch"][0] + event = sent_batch(mock_post)[0] if expected_trace_id is None: self.assertNotIn("$trace_id", event["properties"]) self.assertNotIn("$span_id", event["properties"]) @@ -752,14 +782,14 @@ def test_capture_does_not_attach_otel_span_context_by_default(self, entrypoint): ) with ( - mock.patch("posthog.client.batch_post") as mock_post, + patch_capture_send("client") as mock_post, use_span(NonRecordingSpan(span_context)), ): client = Client(FAKE_TEST_API_KEY, sync_mode=True) capture = getattr(client, entrypoint) capture("$ai_event", distinct_id="distinct_id") - event = mock_post.call_args.kwargs["batch"][0] + event = sent_batch(mock_post)[0] self.assertNotIn("$trace_id", event["properties"]) self.assertNotIn("$span_id", event["properties"]) @@ -896,7 +926,7 @@ def test_capture_exception_logs_when_enabled(self): def test_basic_capture_with_feature_flags(self, patch_flags): patch_flags.return_value = {"featureFlags": {"beta-feature": "random-variant"}} - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -911,7 +941,7 @@ def test_basic_capture_with_feature_flags(self, patch_flags): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "python test event") @@ -1019,7 +1049,7 @@ def test_basic_capture_with_locally_evaluated_feature_flags(self, patch_flags): }, } - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -1036,7 +1066,7 @@ def test_basic_capture_with_locally_evaluated_feature_flags(self, patch_flags): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "python test event") @@ -1057,7 +1087,7 @@ def test_basic_capture_with_locally_evaluated_feature_flags(self, patch_flags): self.assertEqual(patch_flags.call_count, 0) # test that flags are not evaluated without local evaluation - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -1071,7 +1101,7 @@ def test_basic_capture_with_locally_evaluated_feature_flags(self, patch_flags): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] assert "$feature/beta-feature" not in msg["properties"] @@ -1189,7 +1219,7 @@ def test_dont_override_capture_with_local_flags(self, patch_flags): }, } - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -1209,7 +1239,7 @@ def test_dont_override_capture_with_local_flags(self, patch_flags): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "python test event") @@ -1239,7 +1269,7 @@ def test_basic_capture_with_feature_flags_returns_active_only(self, patch_flags) } } - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -1254,7 +1284,7 @@ def test_basic_capture_with_feature_flags_returns_active_only(self, patch_flags) # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "python test event") @@ -1323,7 +1353,7 @@ def test_basic_capture_with_feature_flags_and_disable_geoip_returns_correctly( } } - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, host="https://app.posthog.com", @@ -1344,13 +1374,13 @@ def test_basic_capture_with_feature_flags_and_disable_geoip_returns_correctly( # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "python test event") self.assertTrue(isinstance(msg["timestamp"], str)) self.assertIsNotNone(msg.get("uuid")) - self.assertTrue("$geoip_disable" not in msg["properties"]) + self.assertIs(msg["properties"]["$geoip_disable"], False) self.assertEqual(msg["distinct_id"], "distinct_id") self.assertEqual(msg["properties"]["$lib"], "posthog-python") self.assertEqual(msg["properties"]["$lib_version"], VERSION) @@ -1383,7 +1413,7 @@ def test_basic_capture_with_feature_flags_switched_off_doesnt_send_them( ): patch_flags.return_value = {"featureFlags": {"beta-feature": "random-variant"}} - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -1398,7 +1428,7 @@ def test_basic_capture_with_feature_flags_switched_off_doesnt_send_them( # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "python test event") @@ -1461,7 +1491,7 @@ def test_capture_with_send_feature_flags_false_and_local_evaluation_doesnt_send_ }, } - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -1480,7 +1510,7 @@ def test_capture_with_send_feature_flags_false_and_local_evaluation_doesnt_send_ # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "python test event") @@ -1543,7 +1573,7 @@ def test_capture_with_send_feature_flags_true_and_local_evaluation_uses_local_fl }, } - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -1562,7 +1592,7 @@ def test_capture_with_send_feature_flags_true_and_local_evaluation_uses_local_fl # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "python test event") @@ -1589,7 +1619,7 @@ def test_capture_with_send_feature_flags_options_only_evaluate_locally_true( self, patch_flags ): """Test that SendFeatureFlagsOptions with only_evaluate_locally=True uses local evaluation""" - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -1631,7 +1661,7 @@ def test_capture_with_send_feature_flags_options_only_evaluate_locally_true( # Check the message includes the local flag mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["properties"]["$feature/local-flag"], True) @@ -1644,7 +1674,7 @@ def test_capture_with_send_feature_flags_options_only_evaluate_locally_false( """Test that SendFeatureFlagsOptions with only_evaluate_locally=False forces remote evaluation""" patch_flags.return_value = {"featureFlags": {"remote-flag": "remote-value"}} - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -1678,7 +1708,7 @@ def test_capture_with_send_feature_flags_options_only_evaluate_locally_false( # Check the message includes the remote flag mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["properties"]["$feature/remote-flag"], "remote-value") @@ -1690,7 +1720,7 @@ def test_capture_with_send_feature_flags_options_default_behavior( """Test that SendFeatureFlagsOptions without only_evaluate_locally defaults to remote evaluation""" patch_flags.return_value = {"featureFlags": {"default-flag": "default-value"}} - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -1716,7 +1746,7 @@ def test_capture_with_send_feature_flags_options_default_behavior( # Check the message includes the flag mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual( @@ -1728,7 +1758,7 @@ def test_capture_exception_with_send_feature_flags_options(self, patch_flags): """Test that capture_exception also supports SendFeatureFlagsOptions""" patch_flags.return_value = {"featureFlags": {"exception-flag": True}} - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -1758,7 +1788,7 @@ def test_capture_exception_with_send_feature_flags_options(self, patch_flags): # Check the message includes the flag mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "$exception") @@ -1767,7 +1797,7 @@ def test_capture_exception_with_send_feature_flags_options(self, patch_flags): def test_stringifies_distinct_id(self): # A large number that loses precision in node: # node -e "console.log(157963456373623802 + 1)" > 157963456373623800 - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) msg_uuid = client.capture( "python test event", distinct_id=157963456373623802 @@ -1777,13 +1807,13 @@ def test_stringifies_distinct_id(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["distinct_id"], "157963456373623802") def test_advanced_capture(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) msg_uuid = client.capture( "python test event", @@ -1797,10 +1827,10 @@ def test_advanced_capture(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] - self.assertEqual(msg["timestamp"], "2014-09-03T00:00:00+00:00") + self.assertEqual(msg["timestamp"], "2014-09-03T00:00:00.000000+00:00") self.assertEqual(msg["properties"]["property"], "value") self.assertEqual(msg["event"], "python test event") self.assertEqual(msg["properties"]["$lib"], "posthog-python") @@ -1810,7 +1840,7 @@ def test_advanced_capture(self): self.assertTrue("$groups" not in msg["properties"]) def test_capture_converts_aware_timestamp_to_utc_without_changing_instant(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) client.capture( "python test event", @@ -1820,11 +1850,11 @@ def test_capture_converts_aware_timestamp_to_utc_without_changing_instant(self): ), ) - msg = mock_post.call_args[1]["batch"][0] - self.assertEqual(msg["timestamp"], "2014-09-03T00:00:00+00:00") + msg = sent_batch(mock_post)[0] + self.assertEqual(msg["timestamp"], "2014-09-03T00:00:00.000000+00:00") def test_capture_converts_parseable_timestamp_string_to_utc(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) client.capture( "python test event", @@ -1832,14 +1862,14 @@ def test_capture_converts_parseable_timestamp_string_to_utc(self): timestamp="2014-09-03T05:30:00+05:30", ) - msg = mock_post.call_args[1]["batch"][0] - self.assertEqual(msg["timestamp"], "2014-09-03T00:00:00+00:00") + msg = sent_batch(mock_post)[0] + self.assertEqual(msg["timestamp"], "2014-09-03T00:00:00.000000+00:00") @parameterized.expand(["2026-06-27", "not-an-iso-timestamp"]) def test_capture_replaces_invalid_timestamp_with_current_utc_time(self, timestamp): now = datetime(2026, 6, 27, 12, 30, tzinfo=timezone.utc) with ( - mock.patch("posthog.client.batch_post") as mock_post, + patch_capture_send("client") as mock_post, mock.patch("posthog.client.datetime", wraps=datetime) as mock_datetime, mock.patch.object(Client.log, "warning") as mock_warning, ): @@ -1852,17 +1882,90 @@ def test_capture_replaces_invalid_timestamp_with_current_utc_time(self, timestam ) self.assertIsNotNone(result) - msg = mock_post.call_args[1]["batch"][0] - self.assertEqual(msg["timestamp"], "2026-06-27T12:30:00+00:00") - mock_warning.assert_called_once_with( - "Invalid timestamp %r. Falling back to the current UTC time.", timestamp + msg = sent_batch(mock_post)[0] + self.assertEqual(msg["timestamp"], "2026-06-27T12:30:00.000000+00:00") + mock_warning.assert_called_once() + self.assertNotIn(timestamp, repr(mock_warning.call_args)) + + @parameterized.expand( + [ + (f"{name}_{method}", event, hook_event, method) + for name, event, hook_event in [ + ("missing", None, None), + ("non_string", 123, None), + ("empty", "", None), + ("set_by_before_send", "valid", 123), + ] + for method in ["capture", "capture_ai"] + ] + ) + def test_capture_drops_an_invalid_event_name_and_logs_once( + self, _, event, hook_event, method + ): + def before_send(msg): + if hook_event is not None: + msg["event"] = hook_event + return msg + + with ( + patch_capture_send("client") as mock_post, + mock.patch("posthog.utils._warned_reasons", set()), + mock.patch.object(Client.log, "warning") as mock_warning, + mock.patch.object(Client.log, "exception") as mock_exception, + ): + client = Client(FAKE_TEST_API_KEY, sync_mode=True, before_send=before_send) + capture = getattr(client, method) + results = [capture(event, distinct_id="user") for _ in range(2)] + + self.assertEqual(results, [None, None]) + mock_post.assert_not_called() + mock_warning.assert_called_once() + mock_exception.assert_not_called() + + @parameterized.expand( + [ + ("int", 123), + ("float", 1.5), + ("none", None), + ("list", ["user"]), + ("dict", {"id": "user"}), + ] + ) + def test_capture_drops_an_event_whose_before_send_distinct_id_is_not_a_string( + self, _, bad_id + ): + def before_send(msg): + if msg["event"] == "bad": + msg["distinct_id"] = bad_id + return msg + + with ( + patch_capture_send("client") as mock_post, + mock.patch("posthog.utils._warned_reasons", set()), + mock.patch.object(Client.log, "warning") as mock_warning, + ): + client = Client(FAKE_TEST_API_KEY, sync_mode=True, before_send=before_send) + results = [ + client.capture(event, distinct_id="user") + for event in ("bad", "good", "bad") + ] + + self.assertIsNone(results[0]) + self.assertIsNotNone(results[1]) + self.assertIsNone(results[2]) + self.assertEqual( + [(m["event"], m["distinct_id"]) for m in sent_batch(mock_post)], + [("good", "user")], ) + mock_warning.assert_called_once() + self.assertIn("distinct IDs must be strings", mock_warning.call_args[0][0]) + self.assertNotIn(repr(bad_id), repr(mock_warning.call_args)) def test_capture_does_not_normalize_datetime_properties(self): property_value = datetime( 2014, 9, 3, 5, 30, tzinfo=timezone(timedelta(hours=5, minutes=30)) ) - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) client.capture( "python test event", @@ -1870,11 +1973,11 @@ def test_capture_does_not_normalize_datetime_properties(self): properties={"caller_datetime": property_value}, ) - msg = mock_post.call_args[1]["batch"][0] + msg = sent_batch(mock_post)[0] self.assertIs(msg["properties"]["caller_datetime"], property_value) def test_groups_capture(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) msg_uuid = client.capture( "test_event", @@ -1886,7 +1989,7 @@ def test_groups_capture(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual( @@ -1895,7 +1998,7 @@ def test_groups_capture(self): ) def test_basic_set(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) msg_uuid = client.set( distinct_id="distinct_id", properties={"trait": "value"} @@ -1905,7 +2008,7 @@ def test_basic_set(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["$set"]["trait"], "value") @@ -1914,7 +2017,7 @@ def test_basic_set(self): self.assertEqual(msg["distinct_id"], "distinct_id") def test_advanced_set(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) msg_uuid = client.set( distinct_id="distinct_id", @@ -1927,10 +2030,10 @@ def test_advanced_set(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] - self.assertEqual(msg["timestamp"], "2014-09-03T00:00:00+00:00") + self.assertEqual(msg["timestamp"], "2014-09-03T00:00:00.000000+00:00") self.assertEqual(msg["$set"]["trait"], "value") self.assertEqual(msg["properties"]["$lib"], "posthog-python") self.assertEqual(msg["properties"]["$lib_version"], VERSION) @@ -1939,7 +2042,7 @@ def test_advanced_set(self): self.assertEqual(msg["distinct_id"], "distinct_id") def test_basic_set_once(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) msg_uuid = client.set_once( distinct_id="distinct_id", properties={"trait": "value"} @@ -1949,7 +2052,7 @@ def test_basic_set_once(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["$set_once"]["trait"], "value") @@ -1958,7 +2061,7 @@ def test_basic_set_once(self): self.assertEqual(msg["distinct_id"], "distinct_id") def test_advanced_set_once(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) msg_uuid = client.set_once( distinct_id="distinct_id", @@ -1971,10 +2074,10 @@ def test_advanced_set_once(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] - self.assertEqual(msg["timestamp"], "2014-09-03T00:00:00+00:00") + self.assertEqual(msg["timestamp"], "2014-09-03T00:00:00.000000+00:00") self.assertEqual(msg["$set_once"]["trait"], "value") self.assertEqual(msg["properties"]["$lib"], "posthog-python") self.assertEqual(msg["properties"]["$lib_version"], VERSION) @@ -1983,7 +2086,7 @@ def test_advanced_set_once(self): self.assertEqual(msg["distinct_id"], "distinct_id") def test_basic_group_identify(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) msg_uuid = client.group_identify("organization", "id:5") @@ -1991,7 +2094,7 @@ def test_basic_group_identify(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "$groupidentify") @@ -2011,7 +2114,7 @@ def test_basic_group_identify(self): self.assertIsNotNone(msg.get("uuid")) def test_basic_group_identify_with_distinct_id(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) msg_uuid = client.group_identify( "organization", "id:5", distinct_id="distinct_id" @@ -2020,7 +2123,7 @@ def test_basic_group_identify_with_distinct_id(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "$groupidentify") @@ -2041,7 +2144,7 @@ def test_basic_group_identify_with_distinct_id(self): self.assertIsNotNone(msg.get("uuid")) def test_advanced_group_identify(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) msg_uuid = client.group_identify( "organization", @@ -2055,7 +2158,7 @@ def test_advanced_group_identify(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "$groupidentify") @@ -2071,10 +2174,10 @@ def test_advanced_group_identify(self): "$is_server": True, }, ) - self.assertEqual(msg["timestamp"], "2014-09-03T00:00:00+00:00") + self.assertEqual(msg["timestamp"], "2014-09-03T00:00:00.000000+00:00") def test_advanced_group_identify_with_distinct_id(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) msg_uuid = client.group_identify( "organization", @@ -2089,7 +2192,7 @@ def test_advanced_group_identify_with_distinct_id(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "$groupidentify") @@ -2107,7 +2210,7 @@ def test_advanced_group_identify_with_distinct_id(self): "$is_server": True, }, ) - self.assertEqual(msg["timestamp"], "2014-09-03T00:00:00+00:00") + self.assertEqual(msg["timestamp"], "2014-09-03T00:00:00.000000+00:00") @parameterized.expand( [ @@ -2116,7 +2219,7 @@ def test_advanced_group_identify_with_distinct_id(self): ] ) def test_group_identify_without_group_type_is_dropped(self, _name, group_type): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) with self.assertLogs("posthog", level="WARNING") as logs: msg_uuid = client.group_identify(group_type, "id:5") @@ -2132,7 +2235,7 @@ def test_group_identify_without_group_type_is_dropped(self, _name, group_type): ] ) def test_group_identify_without_group_key_is_dropped(self, _name, group_key): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) with self.assertLogs("posthog", level="WARNING") as logs: msg_uuid = client.group_identify("organization", group_key) @@ -2142,18 +2245,18 @@ def test_group_identify_without_group_key_is_dropped(self, _name, group_key): self.assertIn("group_key", logs.output[0]) def test_group_identify_accepts_falsy_non_string_group_key(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) msg_uuid = client.group_identify("organization", 0) self.assertIsNotNone(msg_uuid) mock_post.assert_called_once() - msg = mock_post.call_args[1]["batch"][0] + msg = sent_batch(mock_post)[0] # The group key is validated, not normalized - it goes out as passed. self.assertEqual(msg["properties"]["$group_key"], 0) def test_basic_alias(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) msg_uuid = client.alias("previousId", "distinct_id") self.assertIsNotNone(msg_uuid) @@ -2161,7 +2264,7 @@ def test_basic_alias(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["properties"]["distinct_id"], "previousId") self.assertEqual(msg["properties"]["alias"], "distinct_id") @@ -2173,7 +2276,7 @@ def test_basic_alias(self): ] ) def test_alias_without_previous_id_is_dropped(self, _name, previous_id): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) with self.assertLogs("posthog", level="WARNING") as logs: msg_uuid = client.alias(previous_id, "distinct_id") @@ -2183,18 +2286,95 @@ def test_alias_without_previous_id_is_dropped(self, _name, previous_id): self.assertIn("previous_id", logs.output[0]) def test_alias_accepts_non_string_previous_id(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) msg_uuid = client.alias(0, "distinct_id") self.assertIsNotNone(msg_uuid) mock_post.assert_called_once() - msg = mock_post.call_args[1]["batch"][0] + msg = sent_batch(mock_post)[0] self.assertEqual(msg["distinct_id"], "0") self.assertEqual(msg["properties"]["distinct_id"], "0") + def _capture_in_request_context(self, call): + with patch_capture_send("client") as mock_post: + client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) + with new_context(fresh=True): + identify_context("context-user") + set_context_session("context-session") + tag("tenant", "acme") + set_context_option("product_tour_id", "tour-1") + result = call(client) + return result, (sent_batch(mock_post)[0] if mock_post.called else None) + + @parameterized.expand( + [ + ("caller_id", "caller-user", "caller-user"), + ("whitespace_caller_id", " ", "context-user"), + ] + ) + def test_group_identify_takes_context_values_but_not_its_session( + self, _, distinct_id, expected_distinct_id + ): + _, msg = self._capture_in_request_context( + lambda client: client.group_identify( + "company", "acme-1", distinct_id=distinct_id + ) + ) + + self.assertEqual(msg["distinct_id"], expected_distinct_id) + self.assertNotIn("$session_id", msg["properties"]) + self.assertEqual(msg["properties"]["tenant"], "acme") + self.assertEqual(msg["options"]["product_tour_id"], "tour-1") + + def test_group_identify_without_any_distinct_id_uses_the_group_id(self): + with patch_capture_send("client") as mock_post: + client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) + client.group_identify("company", "acme-1") + client.group_identify("company", "acme-1") + + self.assertEqual( + [msg["distinct_id"] for msg in sent_events(mock_post)], + ["$company_acme-1", "$company_acme-1"], + ) + + @parameterized.expand( + [ + ("caller_target", "user-1", "user-1"), + ("context_only_target", None, None), + ("whitespace_target", " ", None), + ] + ) + def test_alias_takes_its_target_only_from_the_caller( + self, _, distinct_id, expected_alias + ): + result, msg = self._capture_in_request_context( + lambda client: client.alias("anon-1", distinct_id) + ) + + if expected_alias is None: + self.assertIsNone(result) + self.assertIsNone(msg) + return + self.assertEqual(msg["properties"]["alias"], expected_alias) + self.assertEqual(msg["properties"]["$session_id"], "context-session") + self.assertEqual(msg["properties"]["tenant"], "acme") + self.assertEqual(msg["options"]["product_tour_id"], "tour-1") + + @parameterized.expand([("none", None), ("empty", ""), ("whitespace", " \t ")]) + def test_capture_without_a_distinct_id_sends_a_personless_v7_id( + self, _, distinct_id + ): + with patch_capture_send("client") as mock_post: + client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) + client.capture("event", distinct_id=distinct_id) + + msg = sent_batch(mock_post)[0] + self.assertEqual(UUID(msg["distinct_id"]).version, 7) + self.assertEqual(msg["options"]["process_person_profile"], False) + def test_alias_without_distinct_id_is_dropped(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) with self.assertLogs("posthog", level="WARNING") as logs: msg_uuid = client.alias("previousId", None) @@ -2230,7 +2410,7 @@ def test_alias_without_distinct_id_is_dropped(self): def test_capture_with_session_id_variations( self, test_name, session_id, additional_properties, expected_properties ): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) properties = {"$session_id": session_id, **additional_properties} @@ -2243,7 +2423,7 @@ def test_capture_with_session_id_variations( # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "python test event") @@ -2257,7 +2437,7 @@ def test_capture_with_session_id_variations( self.assertEqual(msg["properties"][key], value) def test_session_id_preserved_with_groups(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) session_id = "group-session-101" @@ -2272,7 +2452,7 @@ def test_session_id_preserved_with_groups(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["properties"]["$session_id"], session_id) @@ -2282,7 +2462,7 @@ def test_session_id_preserved_with_groups(self): ) def test_session_id_with_anonymous_event(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) session_id = "anonymous-session-202" @@ -2299,7 +2479,7 @@ def test_session_id_with_anonymous_event(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["properties"]["$session_id"], session_id) @@ -2379,7 +2559,7 @@ def test_session_id_with_different_event_types( additional_properties, expected_additional_properties, ): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) properties = {"$session_id": session_id, **additional_properties} @@ -2391,7 +2571,7 @@ def test_session_id_with_different_event_types( # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], event_name) @@ -2409,10 +2589,10 @@ def test_session_id_with_different_event_types( [ # test_name, super_properties, event_session_id, expected_session_id, expected_super_props ( - "super_properties_override_session_id", + "event_session_id_overrides_super_properties", {"$session_id": "super-session", "source": "test"}, "event-session-808", - "super-session", + "event-session-808", {"source": "test"}, ), ( @@ -2446,7 +2626,7 @@ def test_session_id_with_super_properties_variations( expected_session_id, expected_super_props, ): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, super_properties=super_properties, sync_mode=True ) @@ -2461,7 +2641,7 @@ def test_session_id_with_super_properties_variations( # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["properties"]["$session_id"], expected_session_id) @@ -2779,22 +2959,94 @@ def flush(timeout_seconds): self.assertEqual(timeouts, [0, None]) - def test_sync_send_failure_does_not_invoke_async_on_error(self): - on_error = mock.Mock() + def test_sync_send_failure_invokes_on_error_after_releasing_send_slot(self): + error = Exception("upload failed") + active_sends_in_callback = [] + client: Client + + def on_error(err, batch): + active_sends_in_callback.append(client._analytics_lane._active_sync_sends) + self.assertIs(err, error) + self.assertEqual([event["event"] for event in batch], ["event"]) + client.shutdown() + + client = Client(FAKE_TEST_API_KEY, sync_mode=True, on_error=on_error) + + with patch_capture_send("client", side_effect=error): + result = client.capture("event", distinct_id="distinct_id") + + self.assertIsNone(result) + self.assertEqual(active_sends_in_callback, [0]) + + def test_sync_send_failure_inside_on_error_logs_instead_of_recursing(self): + calls = [] + client: Client + + def on_error(err, batch): + calls.append(batch[0]["event"]) + client.capture("from_callback", distinct_id="distinct_id") + + client = Client(FAKE_TEST_API_KEY, sync_mode=True, on_error=on_error) + + with patch_capture_send("client", side_effect=Exception("upload failed")): + with self.assertLogs("posthog", level="ERROR") as logs: + client.capture("event", distinct_id="distinct_id") + + self.assertEqual(calls, ["event"]) + self.assertIn( + "1 event(s) not persisted by /i/v1/analytics/events: Exception", + "\n".join(logs.output), + ) + + @parameterized.expand([("capture",), ("capture_ai",)]) + def test_sync_send_failure_in_debug_reports_once_then_raises(self, method_name): + errors = [] client = Client( FAKE_TEST_API_KEY, sync_mode=True, - on_error=on_error, + debug=True, + on_error=lambda err, batch: errors.append(err), ) + failure = APIError(503, "unavailable") - with mock.patch( - "posthog.client.batch_post", side_effect=Exception("upload failed") + with patch_capture_send("client", side_effect=failure): + with self.assertRaises(APIError) as raised: + getattr(client, method_name)("event", distinct_id="distinct_id") + + self.assertIs(raised.exception, failure) + self.assertEqual(errors, [failure]) + + @parameterized.expand( + [ + ("analytics", "capture", _CAPTURE_V1_PATH), + ("ai", "capture_ai", _CAPTURE_AI_V1_PATH), + ] + ) + def test_sync_send_failure_without_on_error_logs_aggregate_line( + self, _name, method_name, path + ): + client = Client(FAKE_TEST_API_KEY, sync_mode=True) + + with patch_capture_send( + "client", side_effect=APIError(400, "password=server-secret") ): - result = client.capture("event", distinct_id="distinct_id") + with self.assertLogs("posthog", level="ERROR") as logs: + result = getattr(client, method_name)( + "$ai_generation", distinct_id="distinct_id" + ) self.assertIsNone(result) - on_error.assert_not_called() - self.assertEqual(client._analytics_lane._active_sync_sends, 0) + output = "\n".join(logs.output) + loss_lines = [ + r.getMessage() + for r in logs.records + if "event(s) not persisted by" in r.getMessage() + ] + self.assertEqual( + loss_lines, + [f"[PostHog] 1 event(s) not persisted by {path}: APIError (status=400)"], + ) + self.assertNotIn("server-secret", output) def test_on_error_can_request_shutdown_with_pending_work(self): first_send_started = threading.Event() @@ -3416,12 +3668,21 @@ def test_shutdown_does_not_wait_for_idle_consumers_flush_interval(self): self.assertLess(time.monotonic() - start, 1) - def test_shutdown_waits_for_racing_enqueue_before_draining(self): + @parameterized.expand( + [ + ("analytics", "capture", "_analytics_lane", _CAPTURE_V1_PATH), + ("ai_first_event", "capture_ai", "_ai_lane", _CAPTURE_AI_V1_PATH), + ] + ) + def test_shutdown_waits_for_racing_enqueue_before_draining( + self, _name, method_name, lane_attr, path + ): client = Client(FAKE_TEST_API_KEY, flush_interval=0.01) + lane = getattr(client, lane_attr) put_started = threading.Event() release_put = threading.Event() shutdown_done = threading.Event() - original_put = client.queue.put + original_put = lane.queue.put capture_result = [] def blocking_put(*args, **kwargs): @@ -3431,14 +3692,17 @@ def blocking_put(*args, **kwargs): capture_thread = threading.Thread( target=lambda: capture_result.append( - client.capture("racing event", distinct_id="distinct_id") + getattr(client, method_name)("$ai_racing", distinct_id="distinct_id") ) ) shutdown_thread = threading.Thread( target=lambda: (client.shutdown(), shutdown_done.set()) ) - with mock.patch.object(client.queue, "put", side_effect=blocking_put): + with ( + patch_capture_send("consumer") as mock_send, + mock.patch.object(lane.queue, "put", side_effect=blocking_put), + ): capture_thread.start() self.assertTrue(put_started.wait(2)) shutdown_thread.start() @@ -3454,7 +3718,17 @@ def blocking_put(*args, **kwargs): self.assertFalse(shutdown_thread.is_alive()) self.assertTrue(shutdown_done.is_set()) self.assertIsNotNone(capture_result[0]) - self.assertTrue(client.queue.empty()) + self.assertTrue(lane.queue.empty()) + self.assertEqual( + [ + (call.kwargs["path"], len(sent_batch(mock_send, i))) + for i, call in enumerate(mock_send.call_args_list) + ], + [(path, 1)], + ) + self.assertFalse( + any(c.is_alive() for lane in client._lanes for c in lane.consumers) + ) def test_shutdown_waits_for_sync_send_and_rejects_later_sends(self): client = Client(FAKE_TEST_API_KEY, sync_mode=True) @@ -3476,7 +3750,7 @@ def blocking_post(*args, **kwargs): target=lambda: (client.shutdown(), shutdown_done.set()) ) - with mock.patch("posthog.client.batch_post", side_effect=blocking_post) as post: + with patch_capture_send("client", side_effect=blocking_post) as post: capture_thread.start() self.assertTrue(send_started.wait(2)) shutdown_thread.start() @@ -3499,7 +3773,7 @@ def blocking_post(*args, **kwargs): post.assert_called_once() def test_synchronous(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, sync_mode=True) msg_uuid = client.capture("test event", distinct_id="distinct_id") @@ -3577,8 +3851,12 @@ def test_numeric_distinct_id(self): def test_debug(self): Client("bad_key", debug=True) - def test_gzip(self): - client = Client(FAKE_TEST_API_KEY, on_error=self.fail, gzip=True) + def test_gzip_compression(self): + client = Client( + FAKE_TEST_API_KEY, + on_error=self.fail, + capture_compression=CaptureCompression.GZIP, + ) for _ in range(10): client.capture( "event", distinct_id="distinct_id", properties={"trait": "value"} @@ -3591,14 +3869,12 @@ def test_user_defined_flush_at(self): FAKE_TEST_API_KEY, on_error=self.fail, flush_at=10, flush_interval=3 ) - def mock_post_fn(*args, **kwargs): - self.assertEqual(len(kwargs["batch"]), 10) + def mock_post_fn(api_key, host, batch, **kwargs): + self.assertEqual(len(batch), 10) # the post function should be called 2 times, with a batch size of 10 # each time. - with mock.patch( - "posthog.consumer.batch_post", side_effect=mock_post_fn - ) as mock_post: + with patch_capture_send("consumer", side_effect=mock_post_fn) as mock_post: for _ in range(20): client.capture( "event", distinct_id="distinct_id", properties={"trait": "value"} @@ -3651,7 +3927,7 @@ def test_disabled_with_feature_flags(self, patch_flags): self.assertTrue(client.queue.empty()) def test_enabled_to_disabled(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -3665,7 +3941,7 @@ def test_enabled_to_disabled(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["event"], "python test event") @@ -3675,7 +3951,7 @@ def test_enabled_to_disabled(self): self.assertFalse(self.failed) def test_disable_geoip_default_on_events(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -3687,12 +3963,12 @@ def test_disable_geoip_default_on_events(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) capture_msg = batch_data[0] self.assertEqual(capture_msg["properties"]["$geoip_disable"], True) def test_disable_geoip_override_on_events(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -3718,17 +3994,17 @@ def test_disable_geoip_override_on_events(self): self.assertEqual(mock_post.call_count, 2) # Check set event - set_batch = mock_post.call_args_list[0][1]["batch"] + set_batch = sent_batch(mock_post, 0) capture_msg = set_batch[0] self.assertEqual(capture_msg["properties"]["$geoip_disable"], True) # Check page event - page_batch = mock_post.call_args_list[1][1]["batch"] + page_batch = sent_batch(mock_post, 1) identify_msg = page_batch[0] - self.assertEqual("$geoip_disable" not in identify_msg["properties"], True) + self.assertIs(identify_msg["properties"]["$geoip_disable"], False) def test_disable_geoip_method_overrides_init_on_events(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -3742,9 +4018,9 @@ def test_disable_geoip_method_overrides_init_on_events(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] - self.assertTrue("$geoip_disable" not in msg["properties"]) + self.assertIs(msg["properties"]["$geoip_disable"], False) @mock.patch("posthog.client.flags") def test_disable_geoip_default_on_decide(self, patch_flags): @@ -4194,7 +4470,7 @@ def test_get_decide_returns_normalized_decide_response(self, patch_flags): } def test_set_context_session_with_capture(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) with new_context(): set_context_session("context-session-123") @@ -4209,7 +4485,7 @@ def test_set_context_session_with_capture(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual( @@ -4218,7 +4494,7 @@ def test_set_context_session_with_capture(self): @parameterized.expand([("new_context",), ("scoped",)]) def test_client_context_helpers_apply_to_capture(self, context_helper): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) def capture_in_context(): @@ -4246,7 +4522,7 @@ def scoped_capture(): self.assertIsNotNone(msg_uuid) mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["distinct_id"], "context-user") @@ -4257,7 +4533,7 @@ def scoped_capture(): self.assertEqual(client.get_tags(), {}) def test_client_scoped_context_helpers_apply_to_capture_async(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) @client.scoped(fresh=True) @@ -4272,7 +4548,7 @@ async def scoped_capture(): self.assertIsNotNone(msg_uuid) mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["distinct_id"], "async-scoped-user") @@ -4288,7 +4564,7 @@ async def scoped_capture(): self.assertEqual(client.get_tags(), {}) def test_set_context_session_with_page_explicit_properties(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) with new_context(): set_context_session("page-explicit-session-789") @@ -4305,7 +4581,7 @@ def test_set_context_session_with_page_explicit_properties(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual( @@ -4316,7 +4592,7 @@ def test_set_context_session_override_in_capture(self): """Test that explicit session ID overrides context session ID in capture""" from posthog.contexts import new_context, set_context_session - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) with new_context(): set_context_session("context-session-override") @@ -4334,7 +4610,7 @@ def test_set_context_session_override_in_capture(self): # Get the enqueued message from the mock mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual( @@ -4537,7 +4813,7 @@ def test_capture_with_send_feature_flags_flag_keys_filter(self, patch_flags): } } - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client( FAKE_TEST_API_KEY, on_error=self.set_fail, @@ -4565,7 +4841,7 @@ def test_capture_with_send_feature_flags_flag_keys_filter(self, patch_flags): # Check the message includes only the filtered flags mock_post.assert_called_once() - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["properties"]["$feature/flag1"], "value1") @@ -4573,7 +4849,7 @@ def test_capture_with_send_feature_flags_flag_keys_filter(self, patch_flags): # flag2 should not be included since it wasn't requested self.assertNotIn("$feature/flag2", msg["properties"]) - @mock.patch("posthog.client.batch_post") + @patch_capture_send("client") def test_get_feature_flag_result_with_empty_string_payload(self, patch_batch_post): """Test that get_feature_flag_result returns a FeatureFlagResult when payload is empty string""" client = Client( @@ -4624,7 +4900,7 @@ def test_get_feature_flag_result_with_empty_string_payload(self, patch_batch_pos self.assertEqual(result.get_value(), "empty-variant") self.assertIsNone(result.payload) - @mock.patch("posthog.client.batch_post") + @patch_capture_send("client") def test_get_all_flags_and_payloads_with_empty_string(self, patch_batch_post): """Test that get_all_flags_and_payloads includes flags with empty string payloads""" client = Client( @@ -4680,14 +4956,14 @@ def test_get_all_flags_and_payloads_with_empty_string(self, patch_batch_post): ) def test_context_tags_added(self): - with mock.patch("posthog.client.batch_post") as mock_post: + with patch_capture_send("client") as mock_post: client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True) with new_context(): tag("random_tag", 12345) client.capture("python test event", distinct_id="distinct_id") - batch_data = mock_post.call_args[1]["batch"] + batch_data = sent_batch(mock_post) msg = batch_data[0] self.assertEqual(msg["properties"]["$context_tags"], ["random_tag"]) @@ -4736,30 +5012,18 @@ def test_debug_flag_re_raises_exceptions(self, mock_enqueue): class TestClientCaptureRetrySemantics(unittest.TestCase): - @parameterized.expand( - [ - ("v0_sync", "v0", True), - ("v1_sync", "v1", True), - ("v0_async", "v0", False), - ("v1_async", "v1", False), - ] - ) - def test_negative_max_retries_still_attempts_delivery_once( - self, _name, capture_mode, sync_mode - ): + @parameterized.expand([("sync", True), ("async", False)]) + def test_negative_max_retries_still_attempts_delivery_once(self, _name, sync_mode): response = mock.Mock(status_code=200, headers={}, text="") response.json.return_value = {"results": {}} client = None - with ( - mock.patch("posthog.client.batch_post") as sync_v0_post, - mock.patch("posthog.consumer.batch_post") as async_v0_post, - mock.patch("posthog.capture_v1._post_v1", return_value=response) as v1_post, - ): + with mock.patch( + "posthog.capture_send._post_v1", return_value=response + ) as v1_post: try: client = Client( FAKE_TEST_API_KEY, - capture_mode=capture_mode, sync_mode=sync_mode, max_retries=-1, flush_at=1, @@ -4770,59 +5034,30 @@ def test_negative_max_retries_still_attempts_delivery_once( client.flush() self.assertEqual(client.max_retries, 0) - if capture_mode == "v1": - v1_post.assert_called_once() - sync_v0_post.assert_not_called() - async_v0_post.assert_not_called() - elif sync_mode: - sync_v0_post.assert_called_once() - async_v0_post.assert_not_called() - v1_post.assert_not_called() - else: - async_v0_post.assert_called_once() - sync_v0_post.assert_not_called() - v1_post.assert_not_called() + v1_post.assert_called_once() finally: if client is not None and not sync_mode: client.shutdown() -class TestClientSyncCaptureMode(unittest.TestCase): - """Sync-mode `_enqueue` selects the analytics submitter by `capture_mode`.""" +class TestClientSyncCapture(unittest.TestCase): + """Sync-mode `_enqueue` sends analytics events through the v1 submitter.""" def _client(self, **kwargs): return Client(FAKE_TEST_API_KEY, sync_mode=True, **kwargs) - @parameterized.expand( - [ - ("v0", None, False), - ("v1", "v1", True), - ] - ) - def test_capture_mode_selects_sync_submitter(self, _name, capture_mode, expects_v1): - kwargs = {"capture_mode": capture_mode} if capture_mode else {} - with ( - mock.patch("posthog.client.batch_post") as mock_post, - mock.patch("posthog.client._send_v1_batch") as mock_v1, - ): - self._client(**kwargs).capture("evt", distinct_id="d") - if expects_v1: - mock_post.assert_not_called() - mock_v1.assert_called_once() - sent_batch = mock_v1.call_args.args[2] - self.assertEqual(len(sent_batch), 1) - self.assertEqual(sent_batch[0]["event"], "evt") - else: - mock_v1.assert_not_called() - mock_post.assert_called_once() - - def test_v1_sync_forwards_config_to_submitter(self): - with ( - mock.patch("posthog.client.batch_post"), - mock.patch("posthog.client._send_v1_batch") as mock_v1, - ): + def test_sync_capture_posts_to_analytics_endpoint(self): + with mock.patch("posthog.client._send_v1_batch") as mock_v1: + self._client().capture("evt", distinct_id="d") + mock_v1.assert_called_once() + batch = mock_v1.call_args.args[2] + self.assertEqual(len(batch), 1) + self.assertEqual(batch[0]["event"], "evt") + self.assertEqual(mock_v1.call_args.kwargs["path"], _CAPTURE_V1_PATH) + + def test_sync_forwards_config_to_submitter(self): + with mock.patch("posthog.client._send_v1_batch") as mock_v1: self._client( - capture_mode="v1", capture_compression=CaptureCompression.GZIP, max_retries=4, historical_migration=True, @@ -4832,29 +5067,15 @@ def test_v1_sync_forwards_config_to_submitter(self): self.assertEqual(kwargs["max_retries"], 4) self.assertEqual(kwargs["historical_migration"], True) - def test_v1_sync_gzip_flag_falls_back_to_gzip_compression(self): - # Legacy `gzip=True` with no explicit capture_compression -> GZIP on v1. - with ( - mock.patch("posthog.client.batch_post"), - mock.patch("posthog.client._send_v1_batch") as mock_v1, - ): - self._client(capture_mode="v1", gzip=True).capture("evt", distinct_id="d") - self.assertEqual( - mock_v1.call_args.kwargs["compression"], CaptureCompression.GZIP - ) - - def test_v1_sync_ai_named_event_through_capture_uses_v1(self): + def test_sync_ai_named_event_through_capture_uses_analytics_endpoint(self): # `capture()` never special-cases AI events: an `$ai_*`-named event - # follows `capture_mode` and rides the v1 submitter like any analytics - # event. Only `capture_ai()` reaches the AI lane. - with ( - mock.patch("posthog.client.batch_post") as mock_post, - mock.patch("posthog.client._send_v1_batch") as mock_v1, - ): - client = self._client(capture_mode="v1") + # rides the analytics endpoint like any other event. Only + # `capture_ai()` reaches the AI lane. + with mock.patch("posthog.client._send_v1_batch") as mock_v1: + client = self._client() client.capture("$ai_generation", distinct_id="d") - mock_post.assert_not_called() mock_v1.assert_called_once() - sent_batch = mock_v1.call_args.args[2] - self.assertEqual(len(sent_batch), 1) - self.assertEqual(sent_batch[0]["event"], "$ai_generation") + batch = mock_v1.call_args.args[2] + self.assertEqual(len(batch), 1) + self.assertEqual(batch[0]["event"], "$ai_generation") + self.assertEqual(mock_v1.call_args.kwargs["path"], _CAPTURE_V1_PATH) diff --git a/posthog/test/test_client_fork.py b/posthog/test/test_client_fork.py index 442322eb5..8b579cde0 100644 --- a/posthog/test/test_client_fork.py +++ b/posthog/test/test_client_fork.py @@ -437,6 +437,7 @@ def test_register_at_fork_reinitializes_poller_and_sessions_in_child_process(sel old_poller = client.poller session_before = posthog.request._get_session() flags_session_before = posthog.request._get_flags_session() + capture_session_before = posthog.request._get_capture_session() def child_probe(): poller_ok = False @@ -456,8 +457,11 @@ def child_probe(): session_after = posthog.request._get_session() flags_session_after = posthog.request._get_flags_session() - sessions_ok = (session_after is not session_before) and ( - flags_session_after is not flags_session_before + capture_session_after = posthog.request._get_capture_session() + sessions_ok = ( + session_after is not session_before + and flags_session_after is not flags_session_before + and capture_session_after is not capture_session_before ) if poller_ok and sessions_ok: diff --git a/posthog/test/test_code_variables.py b/posthog/test/test_code_variables.py index 2efa0bbec..27739006b 100644 --- a/posthog/test/test_code_variables.py +++ b/posthog/test/test_code_variables.py @@ -112,17 +112,16 @@ def extract( import os import posthog from posthog import Posthog -from requests import Response import posthog.request +from posthog.test.capture_helpers import offline_v1_post -def offline_post(url, **kwargs): - response = Response() - response.status_code = 200 - return response +posthog.request._capture_session.post = offline_v1_post -posthog.request._session.post = offline_post +def print_event(event): + print("captured:", event, flush=True) + return event def make_client(**options): @@ -132,6 +131,7 @@ def make_client(**options): debug=True, enable_exception_autocapture=True, project_root=os.path.dirname(os.path.abspath(__file__)), + before_send=print_event, **options, ) """ @@ -141,9 +141,9 @@ def run_app(tmpdir, body, *, env=None): """Write and run a tiny PostHog app that raises an uncaught exception. The app already has ``make_client(**options)`` and ``posthog`` imported; the body - creates the client, defines the failing code, and triggers it. In debug mode the - autocaptured payload (including ``code_variables``) is printed, which is what the - end-to-end tests assert against. Returns the combined stdout/stderr. + creates the client, defines the failing code, and triggers it. A ``before_send`` + hook prints the autocaptured payload (including ``code_variables``), which is what + the end-to-end tests assert against. Returns the combined stdout/stderr. """ app = tmpdir.join("app.py") app.write(_APP_HEADER + "\n" + dedent(body)) @@ -1030,8 +1030,8 @@ def outer(note): class TestEndToEnd: """The whole code-variables pipeline through a real subprocess: an uncaught - exception is autocaptured and its serialized payload (with code_variables) is - printed in debug mode.""" + exception is autocaptured and its payload (with code_variables) is printed by a + before_send hook.""" def test_code_variables_are_captured_and_masked(self, tmpdir): # the failing frame's locals: one safe dict, two secrets, one ignored dunder @@ -1056,7 +1056,7 @@ def trigger_error(): ) assert "ZeroDivisionError" in output assert "'code_variables':" in output # the key form, not the temp-path word - # scalars show up in the debug log in their repr form + # scalars show up in the printed payload in their repr form assert "'greeting': 'hello world'" in output assert "'count': 42" in output # a dict variable is double-encoded as a JSON string (locks the wire format) diff --git a/posthog/test/test_consumer.py b/posthog/test/test_consumer.py index c2c54cf52..f4cf3188d 100644 --- a/posthog/test/test_consumer.py +++ b/posthog/test/test_consumer.py @@ -2,9 +2,6 @@ import threading import time import unittest -from datetime import datetime, timedelta, timezone -from email.utils import format_datetime -from typing import Any from unittest import mock from parameterized import parameterized @@ -15,9 +12,9 @@ from Queue import Queue from posthog.capture_compression import CaptureCompression -from posthog.capture_mode import CaptureMode +from posthog.capture_send import _CAPTURE_AI_V1_PATH, _CAPTURE_V1_PATH from posthog.consumer import MAX_MSG_SIZE, Consumer, _DrainSignal -from posthog.request import AI_EVENTS_ENDPOINT, EVENTS_ENDPOINT, APIError +from posthog.test.capture_helpers import patch_capture_send, sent_batch from posthog.test.logging_helpers import capture_message_only_logs from posthog.test.test_utils import TEST_API_KEY @@ -207,16 +204,37 @@ def test_max_msg_size_param_raises_per_event_ceiling(self) -> None: q.put(big_msg) self.assertEqual(consumer.next(), [big_msg]) + @parameterized.expand( + [ + # A small event serializes to 18 bytes, the "big" one to 81. + ("closes_before_overflow", 43, [0, 1, 2, 3], [[0, 1], [2, 3]]), + ("event_over_limit_goes_alone", 30, [0, "big", 1], [[0], ["big"], [1]]), + ] + ) + def test_batch_byte_limit_is_checked_before_appending( + self, _name, limit, ids, expected + ) -> None: + q = Queue() + consumer = Consumer(q, "", flush_at=10, flush_interval=0.01) + for i in ids: + q.put({"m": "x" * (60 if i == "big" else 1), "i": i}) + + with mock.patch("posthog.consumer.BATCH_SIZE_LIMIT", limit): + batches = [[e["i"] for e in consumer.next()] for _ in expected] + + self.assertEqual(batches, expected) + self.assertEqual(q.unfinished_tasks, len(ids)) + def test_upload(self) -> None: q = Queue() consumer = Consumer(q, TEST_API_KEY, flush_at=1) event = _track_event() q.put(event) - with mock.patch("posthog.consumer.batch_post") as post: + with patch_capture_send("consumer") as post: success = consumer.upload() self.assertTrue(success) post.assert_called_once() - self.assertEqual(post.call_args.kwargs["batch"], [event]) + self.assertEqual(sent_batch(post), [event]) self.assertEqual(q.unfinished_tasks, 0) self.assertTrue(q.empty()) @@ -235,9 +253,11 @@ def test_message_only_error_logs_include_posthog_prefix(self) -> None: # other tests can log into the same stream. Assert on the line under # test rather than on the entire capture. upload_logs = [ - line for line in logs.getvalue().splitlines() if "error uploading" in line + line for line in logs.getvalue().splitlines() if "not persisted" in line ] - expected_log = "[PostHog] error uploading: boom" + expected_log = ( + "[PostHog] 1 event(s) not persisted by /i/v1/analytics/events: Exception" + ) self.assertEqual( [line for line in upload_logs if line == expected_log], [expected_log] ) @@ -307,12 +327,12 @@ def test_multiple_uploads_per_interval(self) -> None: delivered = threading.Event() batches = [] - def record_batch(*args, **kwargs): - batches.append(kwargs["batch"]) + def record_batch(api_key, host, batch, **kwargs): + batches.append(batch) if len(batches) == 2: delivered.set() - with mock.patch("posthog.consumer.batch_post", side_effect=record_batch): + with patch_capture_send("consumer", side_effect=record_batch): consumer.start() try: events = [ @@ -327,86 +347,15 @@ def record_batch(*args, **kwargs): consumer.join(15) self.assertFalse(consumer.is_alive()) - def test_request(self) -> None: - consumer = Consumer(None, TEST_API_KEY) - batch = [_track_event()] - with mock.patch("posthog.consumer.batch_post") as post: - consumer.request(batch) - post.assert_called_once_with( - TEST_API_KEY, - None, - gzip=False, - timeout=15, - batch=batch, - historical_migration=False, - path="/batch/", - ) - - def _run_retry_test( - self, - exception: Exception, - exception_count: int, - retries: int = 10, - expected_attempts: int = 3, - raises: bool = False, - ) -> None: - call_count = [0] - - def mock_post(*args: Any, **kwargs: Any) -> None: - call_count[0] += 1 - if call_count[0] <= exception_count: - raise exception - - consumer = Consumer(None, TEST_API_KEY, retries=retries) - batch = [_track_event()] - with ( - mock.patch("posthog.consumer.batch_post", side_effect=mock_post) as post, - mock.patch("posthog.consumer.time.sleep"), - ): - if raises: - with self.assertRaises(type(exception)) as raised: - consumer.request(batch) - self.assertIs(raised.exception, exception) - else: - consumer.request(batch) - self.assertEqual(post.call_count, expected_attempts) - for call in post.call_args_list: - self.assertEqual(call.kwargs["batch"], batch) - - @parameterized.expand( - [ - ("general_errors", Exception("generic exception"), 2), - ("server_errors", APIError(500, "Internal Server Error"), 2), - ("rate_limit_errors", APIError(429, "Too Many Requests"), 2), - ] - ) - def test_request_retries_on_retriable_errors( - self, _name: str, exception: Exception, exception_count: int - ) -> None: - self._run_retry_test(exception, exception_count) - - def test_request_does_not_retry_client_errors(self) -> None: - self._run_retry_test( - APIError(400, "Client Errors"), 1, expected_attempts=1, raises=True - ) - - def test_request_fails_when_exceptions_exceed_retries(self) -> None: - self._run_retry_test( - APIError(500, "Internal Server Error"), - 4, - retries=3, - expected_attempts=4, - raises=True, - ) - def test_negative_retries_still_attempts_delivery_once(self) -> None: consumer = Consumer(None, TEST_API_KEY, retries=-1) - with mock.patch("posthog.consumer.batch_post") as mock_post: + with patch_capture_send("consumer") as mock_send: consumer.request([_track_event()]) self.assertEqual(consumer.retries, 0) - mock_post.assert_called_once() + mock_send.assert_called_once() + self.assertEqual(mock_send.call_args.kwargs["max_retries"], 0) def test_pause(self) -> None: consumer = Consumer(None, TEST_API_KEY) @@ -602,7 +551,7 @@ def test_max_batch_size(self) -> None: # Let's capture 8MB of data to trigger two batches n_msgs = int(8_000_000 / msg_size) - with mock.patch.object(consumer, "_send") as mock_send: + with mock.patch.object(consumer, "request") as mock_send: consumer.start() try: for _ in range(0, n_msgs + 2): @@ -620,101 +569,6 @@ def test_max_batch_size(self) -> None: consumer.join(5) self.assertFalse(consumer.is_alive()) - def test_request_sleeps_with_retry_after(self) -> None: - error = APIError(429, "Too Many Requests", retry_after=5.0) - call_count = [0] - - def mock_post(*args: Any, **kwargs: Any) -> None: - call_count[0] += 1 - if call_count[0] <= 1: - raise error - - consumer = Consumer(None, TEST_API_KEY, retries=3) - with ( - mock.patch("posthog.consumer.batch_post", side_effect=mock_post), - mock.patch("posthog.consumer.time.sleep") as mock_sleep, - ): - consumer.request([_track_event()]) - mock_sleep.assert_called_once_with(5.0) - - def test_request_uses_exponential_backoff_without_retry_after(self) -> None: - error = APIError(503, "Service Unavailable") - call_count = [0] - - def mock_post(*args: Any, **kwargs: Any) -> None: - call_count[0] += 1 - if call_count[0] <= 3: - raise error - - consumer = Consumer(None, TEST_API_KEY, retries=3) - with ( - mock.patch("posthog.consumer.batch_post", side_effect=mock_post), - mock.patch("posthog.consumer.time.sleep") as mock_sleep, - ): - consumer.request([_track_event()]) - self.assertEqual( - mock_sleep.call_args_list, - [ - mock.call(1), # 2^0 - mock.call(2), # 2^1 - mock.call(4), # 2^2 - ], - ) - - @parameterized.expand( - [ - ("huge_numeric", "1000000000", [30, 30]), - ("small_numeric", "0.25", [1, 2]), - ("huge_date", "Fri, 01 Jan 2100 00:00:00 GMT", [30, 30]), - ("small_date", None, [1, 2]), - ] - ) - def test_request_bounds_retry_after_without_reducing_attempts( - self, _name: str, retry_after_header: str | None, expected_sleeps: list[int] - ) -> None: - if retry_after_header is None: - retry_after_header = format_datetime( - datetime.now(timezone.utc) + timedelta(seconds=1), usegmt=True - ) - - retry_response = mock.Mock( - status_code=503, - headers={"Retry-After": retry_after_header}, - text="Service Unavailable", - ) - retry_response.json.return_value = {"detail": "Service Unavailable"} - success_response = mock.Mock(status_code=200) - session = mock.Mock() - session.post.side_effect = [retry_response, retry_response, success_response] - - consumer = Consumer(None, TEST_API_KEY, retries=2) - with ( - mock.patch("posthog.request._get_session", return_value=session), - mock.patch("posthog.consumer.time.sleep") as mock_sleep, - ): - consumer.request([_track_event()]) - - self.assertEqual(session.post.call_count, 3) - self.assertEqual( - [call.args[0] for call in mock_sleep.call_args_list], expected_sleeps - ) - - def test_request_retries_on_408(self) -> None: - call_count = [0] - - def mock_post(*args: Any, **kwargs: Any) -> None: - call_count[0] += 1 - if call_count[0] <= 1: - raise APIError(408, "Request Timeout") - - consumer = Consumer(None, TEST_API_KEY, retries=3) - with ( - mock.patch("posthog.consumer.batch_post", side_effect=mock_post), - mock.patch("posthog.consumer.time.sleep"), - ): - consumer.request([_track_event()]) - self.assertEqual(call_count[0], 2) - @parameterized.expand( [ ("on_error_succeeds", False), @@ -751,48 +605,28 @@ def _ai_event(event_name: str = "$ai_generation") -> dict[str, str]: return {"type": "track", "event": event_name, "distinct_id": "distinct_id"} -class TestConsumerCaptureModeRouting(unittest.TestCase): - """`capture_mode` selects the submitter; V0 posts to the consumer's `endpoint`.""" +class TestConsumerSubmitterRouting(unittest.TestCase): + """Every consumer sends through the capture v1 submitter to its `endpoint`.""" - @parameterized.expand( - [ - ("v0", CaptureMode.V0, False), - ("v1", CaptureMode.V1, True), - ] - ) - def test_capture_mode_selects_analytics_submitter( - self, _name, mode, expects_v1 - ) -> None: - consumer = Consumer(None, TEST_API_KEY, capture_mode=mode) + def test_default_posts_to_analytics_endpoint(self) -> None: + consumer = Consumer(None, TEST_API_KEY) batch = [_track_event()] - with ( - mock.patch("posthog.consumer.batch_post") as mock_post, - mock.patch("posthog.consumer._send_v1_batch") as mock_v1, - ): + with patch_capture_send("consumer") as mock_v1: consumer.request(batch) - if expects_v1: - mock_post.assert_not_called() - mock_v1.assert_called_once() - self.assertEqual(mock_v1.call_args.args[2], batch) - else: - mock_v1.assert_not_called() - mock_post.assert_called_once() - self.assertEqual(mock_post.call_args.kwargs["path"], EVENTS_ENDPOINT) - - def test_v1_forwards_consumer_config_to_submitter(self) -> None: + mock_v1.assert_called_once() + self.assertEqual(sent_batch(mock_v1), batch) + self.assertEqual(mock_v1.call_args.kwargs["path"], _CAPTURE_V1_PATH) + + def test_forwards_consumer_config_to_submitter(self) -> None: consumer = Consumer( None, TEST_API_KEY, - capture_mode=CaptureMode.V1, capture_compression=CaptureCompression.DEFLATE, timeout=7, retries=4, historical_migration=True, ) - with ( - mock.patch("posthog.consumer.batch_post"), - mock.patch("posthog.consumer._send_v1_batch") as mock_v1, - ): + with patch_capture_send("consumer") as mock_v1: consumer.request([_track_event()]) kwargs = mock_v1.call_args.kwargs self.assertEqual(kwargs["compression"], CaptureCompression.DEFLATE) @@ -800,25 +634,11 @@ def test_v1_forwards_consumer_config_to_submitter(self) -> None: self.assertEqual(kwargs["max_retries"], 4) self.assertEqual(kwargs["historical_migration"], True) - def test_v0_posts_to_configured_endpoint(self) -> None: - consumer = Consumer(None, TEST_API_KEY, endpoint=AI_EVENTS_ENDPOINT) + def test_posts_to_configured_endpoint(self) -> None: + consumer = Consumer(None, TEST_API_KEY, endpoint=_CAPTURE_AI_V1_PATH) batch = [_ai_event()] - with mock.patch("posthog.consumer.batch_post") as mock_post: - consumer.request(batch) - mock_post.assert_called_once() - self.assertEqual(mock_post.call_args.kwargs["path"], AI_EVENTS_ENDPOINT) - self.assertEqual(mock_post.call_args.kwargs["batch"], batch) - - def test_v1_routes_whole_batch_through_v1_submitter(self) -> None: - # A consumer doesn't know AI events exist: with `capture_mode` v1, the - # whole batch (including `$ai_*`-named events) rides the v1 submitter. - consumer = Consumer(None, TEST_API_KEY, capture_mode=CaptureMode.V1) - batch = [_ai_event(), _track_event()] - with ( - mock.patch("posthog.consumer.batch_post") as mock_post, - mock.patch("posthog.consumer._send_v1_batch") as mock_v1, - ): + with patch_capture_send("consumer") as mock_v1: consumer.request(batch) - mock_v1.assert_called_once() - self.assertEqual(mock_v1.call_args.args[2], batch) - mock_post.assert_not_called() + mock_v1.assert_called_once() + self.assertEqual(mock_v1.call_args.kwargs["path"], _CAPTURE_AI_V1_PATH) + self.assertEqual(sent_batch(mock_v1), batch) diff --git a/posthog/test/test_contexts.py b/posthog/test/test_contexts.py index b8c57e96c..7efc7e0fc 100644 --- a/posthog/test/test_contexts.py +++ b/posthog/test/test_contexts.py @@ -8,7 +8,9 @@ from posthog.async_client import AsyncPosthog from posthog.client import Client from posthog.contexts import ( + get_context_options, get_tags, + set_context_option, new_context, scoped, tag, @@ -400,6 +402,26 @@ def context_state(): ), ) + def test_context_options_inherit_like_tags(self): + with new_context(fresh=True): + set_context_option("cookieless_mode", True) + set_context_option("process_person_profile", False) + + with new_context(fresh=False): + set_context_option("process_person_profile", True) + assert get_context_options() == { + "cookieless_mode": True, + "process_person_profile": True, + } + + with new_context(fresh=True): + assert get_context_options() == {} + + assert get_context_options() == { + "cookieless_mode": True, + "process_person_profile": False, + } + def test_child_tags_override_parent_tags_in_non_fresh_context(self): with new_context(fresh=True): tag("shared_key", "parent_value") diff --git a/posthog/test/test_evaluate_flags.py b/posthog/test/test_evaluate_flags.py index 2546c08f9..89a8c71f0 100644 --- a/posthog/test/test_evaluate_flags.py +++ b/posthog/test/test_evaluate_flags.py @@ -1141,7 +1141,8 @@ class TestUnresolvableFlagWarning(unittest.TestCase): def _client(self, **kwargs): client = Client( FAKE_TEST_API_KEY, - secret_key="test", + # A key no other test uses, so a poller leaked by another module never matches it. + secret_key="test-unresolvable-flag-warning", enable_local_evaluation=False, send=False, **kwargs, @@ -1437,7 +1438,14 @@ def _refresh_from(self, client, source, *flags): mock.patch("posthog.client.get") as get, ): client._load_feature_flags() - get.assert_not_called() + # Pollers left running by other test modules share the patched + # module-level `get`, so only this client's key counts. + own_calls = [ + call + for call in get.call_args_list + if call.args and call.args[0] == client.personal_api_key + ] + self.assertEqual(own_calls, []) @staticmethod def _never_resolvable_flag(key, reason, **kwargs): @@ -1817,7 +1825,7 @@ def test_capture_with_flags_attaches_feature_properties( None, ) self.assertIsNotNone(page_viewed) - properties = page_viewed[0][0]["properties"] + properties = page_viewed.kwargs["flag_properties"] self.assertEqual(properties["$feature/variant-flag"], "variant-value") self.assertEqual(properties["$feature/boolean-flag"], True) self.assertEqual(properties["$feature/disabled-flag"], False) @@ -1847,7 +1855,7 @@ def test_capture_with_only_accessed_attaches_only_those_flags( ), None, ) - properties = page_viewed[0][0]["properties"] + properties = page_viewed.kwargs["flag_properties"] self.assertEqual(properties["$feature/boolean-flag"], True) self.assertNotIn("$feature/variant-flag", properties) self.assertNotIn("$feature/disabled-flag", properties) diff --git a/posthog/test/test_event_options.py b/posthog/test/test_event_options.py new file mode 100644 index 000000000..9a0969e4c --- /dev/null +++ b/posthog/test/test_event_options.py @@ -0,0 +1,1259 @@ +import inspect +import logging + +import pytest +from opentelemetry.trace import NonRecordingSpan, SpanContext, TraceFlags, use_span + +from posthog import AsyncPosthog, new_context, set_context_option, tag +from posthog.ai.utils import _capture_ai_event +from posthog.capture_event import _to_v1_event +from posthog.client import Client +from posthog.test.capture_helpers import ( + patch_async_capture_send, + patch_capture_send, + sent_events, +) +from posthog.test.test_utils import FAKE_TEST_API_KEY +from posthog.version import VERSION + +OPTIONS = {"cookieless_mode": True, "future_option": "kept"} +PP = "process_person_profile" +LEGACY_PP = "$process_person_profile" + +CAPTURE_CALLS = { + "capture": lambda c, o: c.capture("e", distinct_id="u", options=o), + "capture_ai": lambda c, o: c.capture_ai( + "$ai_generation", distinct_id="u", options=o + ), + "set": lambda c, o: c.set(distinct_id="u", properties={"a": 1}, options=o), + "set_once": lambda c, o: c.set_once( + distinct_id="u", properties={"a": 1}, options=o + ), + "group_identify": lambda c, o: c.group_identify( + "company", "acme", distinct_id="u", options=o + ), + "alias": lambda c, o: c.alias("previous", "u", options=o), + "capture_exception": lambda c, o: c.capture_exception( + ValueError("boom"), distinct_id="u", options=o + ), +} +ASYNC_CAPTURE_CALLS = {k: v for k, v in CAPTURE_CALLS.items() if k != "capture_ai"} +ASYNC_LIBRARY_CALLS = {**ASYNC_CAPTURE_CALLS, "capture_ai": CAPTURE_CALLS["capture_ai"]} +# These methods send identify-style events, which default person processing on. +IDENTIFY_STYLE_METHODS = {"set", "set_once", "group_identify", "alias"} + + +def _expected_options(method, options): + return {**options, PP: True} if method in IDENTIFY_STYLE_METHODS else options + + +def _sync_wire_events(call, before_send=None, **config) -> list[dict]: + with patch_capture_send("client") as send: + client = Client( + FAKE_TEST_API_KEY, sync_mode=True, before_send=before_send, **config + ) + assert call(client) is not None + return [_to_v1_event(msg) for msg in sent_events(send)] + + +async def _async_wire_events(call, before_send=None, **config) -> list[dict]: + batches: list[list[dict]] = [] + + async def send_batch(api_key, host, batch, **kwargs): + batches.append(batch) + + with patch_async_capture_send(side_effect=send_batch): + async with AsyncPosthog( + "test-key", before_send=before_send, **config + ) as client: + result = call(client) + if inspect.isawaitable(result): + result = await result + assert result is not None + await client.flush(timeout_seconds=1) + return [_to_v1_event(msg) for batch in batches for msg in batch] + + +@pytest.mark.parametrize("method", list(CAPTURE_CALLS)) +def test_sync_options_reach_the_wire(method): + events = _sync_wire_events(lambda c: CAPTURE_CALLS[method](c, OPTIONS)) + assert [e["options"] for e in events] == [_expected_options(method, OPTIONS)] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("method", list(ASYNC_CAPTURE_CALLS)) +async def test_async_options_reach_the_wire(method): + events = await _async_wire_events(lambda c: ASYNC_CAPTURE_CALLS[method](c, OPTIONS)) + assert [e["options"] for e in events] == [_expected_options(method, OPTIONS)] + + +def _hook(msg): + properties = {k: v for k, v in msg["properties"].items() if k != "$product_tour_id"} + return {**msg, "options": {"cookieless_mode": False}, "properties": properties} + + +def _hooked_capture(client): + return client.capture( + "e", + distinct_id="u", + properties={"$product_tour_id": "tour-1"}, + options={"cookieless_mode": True}, + ) + + +def test_sync_before_send_changes_options_and_legacy_properties(): + events = _sync_wire_events(_hooked_capture, before_send=_hook) + assert events[0]["options"] == {"cookieless_mode": False} + + +@pytest.mark.asyncio +async def test_async_before_send_changes_options_and_legacy_properties(): + events = await _async_wire_events(_hooked_capture, before_send=_hook) + assert events[0]["options"] == {"cookieless_mode": False} + + +def test_sync_non_dict_options_are_logged_and_event_is_sent(caplog): + with caplog.at_level(logging.ERROR, logger="posthog"): + events = _sync_wire_events( + lambda c: c.capture("e", distinct_id="u", options=["cookieless_mode"]) + ) + assert events[0]["options"] == {} + assert "options must be a dict" in caplog.text + + +@pytest.mark.asyncio +async def test_async_non_dict_options_are_logged_and_event_is_sent(caplog): + with caplog.at_level(logging.ERROR, logger="posthog"): + events = await _async_wire_events( + lambda c: c.capture("e", distinct_id="u", options=["cookieless_mode"]) + ) + assert events[0]["options"] == {} + assert "options must be a dict" in caplog.text + + +# Layers, lowest first: personless (no distinct_id), super, context, event. +LAYER_CASES = { + "personless_alone": ({}, {}, {}, None, {PP: False}), + "identified_sends_no_option": ({}, {}, {}, "u", {}), + "super_beats_personless": ({PP: True}, {}, {}, None, {PP: True}), + "context_beats_super": ({PP: True}, {PP: False}, {}, "u", {PP: False}), + "event_beats_context": ({}, {PP: False}, {PP: True}, "u", {PP: True}), + "event_beats_all": ({PP: False}, {PP: False}, {PP: True}, None, {PP: True}), + "null_event_option_is_filled": ({PP: True}, {}, {PP: None}, "u", {PP: True}), + "layers_merge_by_key": ( + {"cookieless_mode": True}, + {"product_tour_id": "t"}, + {}, + "u", + {"cookieless_mode": True, "product_tour_id": "t"}, + ), +} + + +def _layered_capture(context_options, event_options, distinct_id): + def call(client): + with new_context(fresh=True): + for key, value in context_options.items(): + set_context_option(key, value) + return client.capture("e", distinct_id=distinct_id, options=event_options) + + return call + + +@pytest.mark.parametrize("case", list(LAYER_CASES)) +def test_sync_option_layers(case): + super_options, context, event, distinct_id, expected = LAYER_CASES[case] + events = _sync_wire_events( + _layered_capture(context, event, distinct_id), super_options=super_options + ) + assert events[0]["options"] == expected + + +@pytest.mark.asyncio +@pytest.mark.parametrize("case", list(LAYER_CASES)) +async def test_async_option_layers(case): + super_options, context, event, distinct_id, expected = LAYER_CASES[case] + events = await _async_wire_events( + _layered_capture(context, event, distinct_id), super_options=super_options + ) + assert events[0]["options"] == expected + + +@pytest.mark.parametrize( + "method", ["capture", "set", "set_once", "group_identify", "alias"] +) +def test_sync_super_options_reach_every_path(method): + events = _sync_wire_events( + lambda c: CAPTURE_CALLS[method](c, None), super_options=OPTIONS + ) + assert [e["options"] for e in events] == [_expected_options(method, OPTIONS)] + + +@pytest.mark.parametrize("method", ["capture", "set", "set_once"]) +def test_sync_context_options_reach_user_paths(method): + def call(client): + with new_context(fresh=True): + set_context_option("cookieless_mode", True) + return CAPTURE_CALLS[method](client, None) + + events = _sync_wire_events(call) + assert [e["options"] for e in events] == [ + _expected_options(method, {"cookieless_mode": True}) + ] + + +@pytest.mark.parametrize( + "event, expected", [("e", False), ("$identify", True)], ids=["other", "identify"] +) +def test_personless_option_against_legacy_property(event, expected): + # An identify-style event takes the call's legacy property before the + # personless default fills. + events = _sync_wire_events(lambda c: c.capture(event, properties={LEGACY_PP: True})) + assert events[0]["options"] == {PP: expected} + assert LEGACY_PP not in events[0]["properties"] + + +@pytest.mark.parametrize( + "event, expected", [("e", False), ("$identify", True)], ids=["other", "identify"] +) +def test_legacy_super_property_fills_option_when_unset(event, expected): + events = _sync_wire_events( + lambda c: c.capture(event, distinct_id="u"), + super_properties={LEGACY_PP: False}, + ) + assert events[0]["options"] == {PP: expected} + + +def _layered_properties(client): + with new_context(fresh=True): + tag("from_context", "context") + tag("shared", "context") + return client.capture( + "e", distinct_id="u", properties={"shared": "event", "only_event": 1} + ) + + +SUPER_PROPERTIES = {"shared": "super", "from_context": "super", "only_super": 1} + + +def test_sync_event_and_context_properties_beat_super_properties(): + events = _sync_wire_events(_layered_properties, super_properties=SUPER_PROPERTIES) + properties = events[0]["properties"] + assert ( + properties["shared"], + properties["from_context"], + properties["only_super"], + properties["only_event"], + ) == ("event", "context", 1, 1) + + +@pytest.mark.asyncio +async def test_async_event_and_context_properties_beat_super_properties(): + events = await _async_wire_events( + _layered_properties, super_properties=SUPER_PROPERTIES + ) + properties = events[0]["properties"] + assert ( + properties["shared"], + properties["from_context"], + properties["only_super"], + properties["only_event"], + ) == ("event", "context", 1, 1) + + +DEFAULTS_CONFIG = { + "super_properties": {"shared": "super", "only_super": 1}, + "super_options": {"cookieless_mode": True}, +} + + +def _recording_hook(seen): + def hook(msg): + seen.append((dict(msg["properties"]), dict(msg["options"]))) + removed = {"only_super", "$is_server"} + properties = { + **{k: v for k, v in msg["properties"].items() if k not in removed}, + "shared": "hook", + } + return {**msg, "properties": properties, "options": {"cookieless_mode": False}} + + return hook + + +def _set_context_values(): + tag("from_context", "context") + set_context_option("product_tour_id", "context-tour") + + +def _context_capture(method): + def call(client): + if method == "capture": + with new_context(fresh=True): + _set_context_values() + return client.capture("e", distinct_id="u") + + async def immediate(): + with new_context(fresh=True): + _set_context_values() + return await client.capture_immediate("e", distinct_id="u") + + return immediate() + + return call + + +def _assert_hook_sees_defaults_and_has_final_say(seen, events): + hook_properties, hook_options = seen[0] + assert ( + hook_properties["shared"], + hook_properties["only_super"], + hook_properties["from_context"], + hook_properties["$is_server"], + hook_properties["$geoip_disable"], + ) == ("super", 1, "context", True, True) + assert "$os" in hook_properties + assert hook_options == {"cookieless_mode": True, "product_tour_id": "context-tour"} + properties = events[0]["properties"] + assert (properties["shared"], properties["from_context"]) == ("hook", "context") + assert not {"only_super", "$is_server"} & properties.keys() + assert events[0]["options"] == {"cookieless_mode": False} + + +def test_sync_defaults_fill_before_before_send(): + seen: list = [] + events = _sync_wire_events( + _context_capture("capture"), + before_send=_recording_hook(seen), + **DEFAULTS_CONFIG, + ) + _assert_hook_sees_defaults_and_has_final_say(seen, events) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("method", ["capture", "capture_immediate"]) +async def test_async_defaults_fill_before_before_send(method): + seen: list = [] + events = await _async_wire_events( + _context_capture(method), before_send=_recording_hook(seen), **DEFAULTS_CONFIG + ) + _assert_hook_sees_defaults_and_has_final_say(seen, events) + + +@pytest.mark.asyncio +async def test_async_queued_event_keeps_capture_time_defaults(): + def capture_then_change_defaults(client): + result = client.capture("e", distinct_id="d") + client.super_properties["plan"] = "pro" + client.super_options["cookieless_mode"] = True + return result + + events = await _async_wire_events( + capture_then_change_defaults, + super_properties={"plan": "free"}, + super_options={"cookieless_mode": False}, + ) + assert events[0]["properties"]["plan"] == "free" + assert events[0]["options"]["cookieless_mode"] is False + + +NESTED_SUPER_PROPERTIES = { + "$set": {"plan": "free", "source": "super"}, + "$groups": {"company": "acme", "team": "core", "region": "us"}, + "$unset": ["stale"], +} + + +def _nested_capture(client): + return client.capture( + "e", + distinct_id="u", + properties={ + "$set": {"plan": "pro"}, + "$unset": ["other"], + "$groups": {"company": "event", "team": "event"}, + }, + groups={"company": "posthog"}, + ) + + +def _assert_nested_properties(events): + properties = events[0]["properties"] + assert properties["$set"] == {"plan": "pro", "source": "super"} + assert properties["$groups"] == { + "company": "posthog", + "team": "event", + "region": "us", + } + assert properties["$unset"] == ["other"] + + +def test_nested_properties_fill_one_level_deep(): + events = _sync_wire_events( + _nested_capture, super_properties=NESTED_SUPER_PROPERTIES + ) + _assert_nested_properties(events) + + +@pytest.mark.asyncio +async def test_async_nested_properties_fill_one_level_deep(): + events = await _async_wire_events( + _nested_capture, super_properties=NESTED_SUPER_PROPERTIES + ) + _assert_nested_properties(events) + + +CALLER_SDK_VALUES = { + "$is_server": False, + "$geoip_disable": False, + "$os": "caller-os", + "$lib": "caller-lib", + "$lib_version": "caller-version", +} +SDK_FLAGS = {"$is_server": False, "$geoip_disable": False} +SDK_LIBRARY = {"$lib": "posthog-python", "$lib_version": VERSION} +CALLER_LIBRARY = {"$lib": "caller-lib", "$lib_version": "caller-version"} + + +def _capture_with_caller_sdk_values(source): + def call(client): + with new_context(fresh=True): + if source == "context": + for key, value in CALLER_SDK_VALUES.items(): + tag(key, value) + properties = CALLER_SDK_VALUES if source == "event" else None + return client.capture("e", distinct_id="u", properties=properties) + + return call + + +def _sdk_value_config(source): + return {"super_properties": CALLER_SDK_VALUES} if source == "super" else {} + + +def _assert_caller_values(events, expected): + properties = events[0]["properties"] + assert {key: properties.get(key) for key in expected} == expected + + +@pytest.mark.parametrize("source", ["event", "context", "super"]) +def test_sync_caller_values_beat_sdk_values(source): + events = _sync_wire_events( + _capture_with_caller_sdk_values(source), **_sdk_value_config(source) + ) + _assert_caller_values(events, CALLER_SDK_VALUES) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("source", ["event", "context", "super"]) +async def test_async_caller_values_beat_sdk_values(source): + events = await _async_wire_events( + _capture_with_caller_sdk_values(source), **_sdk_value_config(source) + ) + _assert_caller_values(events, CALLER_SDK_VALUES) + + +class _FlagSnapshot: + def _get_event_properties(self): + return {"$feature/beta": "snapshot", "$active_feature_flags": ["beta"]} + + +def _capture_with_flags_and_caller_value(source): + def call(client): + with new_context(fresh=True): + if source == "context": + tag("$feature/beta", "caller") + properties = {"$feature/beta": "caller"} if source == "event" else None + return client.capture( + "e", distinct_id="u", properties=properties, flags=_FlagSnapshot() + ) + + return call + + +def _flag_layer_config(source): + return ( + {"super_properties": {"$feature/beta": "caller"}} if source == "super" else {} + ) + + +def _assert_flag_layers(events, source): + properties = events[0]["properties"] + expected = "snapshot" if source is None else "caller" + assert properties["$feature/beta"] == expected + assert properties["$active_feature_flags"] == ["beta"] + + +@pytest.mark.parametrize("source", ["event", "context", "super", None]) +def test_sync_caller_layers_beat_flag_properties(source): + events = _sync_wire_events( + _capture_with_flags_and_caller_value(source), **_flag_layer_config(source) + ) + _assert_flag_layers(events, source) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("source", ["event", "context", "super", None]) +async def test_async_caller_layers_beat_flag_properties(source): + events = await _async_wire_events( + _capture_with_flags_and_caller_value(source), **_flag_layer_config(source) + ) + _assert_flag_layers(events, source) + + +SPAN_IDS = { + "$trace_id": "00000000000000000000000000000123", + "$span_id": "0000000000000456", +} + +# Each caller layer sets one key of the pair, so the SDK adds neither span id. +TRACE_ID_CASES = [ + pytest.param(None, SPAN_IDS, id="no_layer"), + pytest.param("event", {"$trace_id": "caller"}, id="event_trace_id"), + pytest.param("context", {"$trace_id": "caller"}, id="context_trace_id"), + pytest.param("super", {"$span_id": "caller"}, id="super_span_id"), +] + +TRACE_CALLS = { + "capture": lambda c, p: c.capture("e", distinct_id="u", properties=p), + "capture_ai": lambda c, p: c.capture_ai( + "$ai_generation", distinct_id="u", properties=p + ), + "capture_exception": lambda c, p: c.capture_exception( + ValueError("boom"), distinct_id="u", properties=p + ), +} + + +def _capture_in_span(method, source=None): + span = NonRecordingSpan( + SpanContext( + trace_id=0x123, + span_id=0x456, + is_remote=False, + trace_flags=TraceFlags.SAMPLED, + ) + ) + + def call(client): + with new_context(fresh=True), use_span(span): + if source == "context": + tag("$trace_id", "caller") + properties = {"$trace_id": "caller"} if source == "event" else None + return TRACE_CALLS[method](client, properties) + + return call + + +def _trace_config(source, capture_trace_context=True): + config: dict = {"capture_trace_context": capture_trace_context} + if source == "super": + config["super_properties"] = {"$span_id": "caller"} + return config + + +def _span_ids(properties): + return {k: properties[k] for k in SPAN_IDS if k in properties} + + +def _trace_context_setting(method): + # capture_exception adds the span ids even with capture_trace_context off. + return method != "capture_exception" + + +@pytest.mark.parametrize("method", list(TRACE_CALLS)) +@pytest.mark.parametrize("source,expected", TRACE_ID_CASES) +def test_sync_span_ids_fill_as_a_pair_below_caller_layers(method, source, expected): + events = _sync_wire_events( + _capture_in_span(method, source), + **_trace_config(source, _trace_context_setting(method)), + ) + assert _span_ids(events[0]["properties"]) == expected + + +@pytest.mark.asyncio +@pytest.mark.parametrize("method", list(TRACE_CALLS)) +@pytest.mark.parametrize("source,expected", TRACE_ID_CASES) +async def test_async_span_ids_fill_as_a_pair_below_caller_layers( + method, source, expected +): + events = await _async_wire_events( + _capture_in_span(method, source), + **_trace_config(source, _trace_context_setting(method)), + ) + assert _span_ids(events[0]["properties"]) == expected + + +def _span_id_hook(seen): + def hook(msg): + seen.append(_span_ids(msg["properties"])) + return {**msg, "properties": {**msg["properties"], "$span_id": "hook"}} + + return hook + + +@pytest.mark.parametrize("method", list(TRACE_CALLS)) +def test_sync_before_send_sees_and_changes_span_ids(method): + seen: list = [] + events = _sync_wire_events( + _capture_in_span(method), + before_send=_span_id_hook(seen), + **_trace_config(None, _trace_context_setting(method)), + ) + assert seen == [SPAN_IDS] + assert _span_ids(events[0]["properties"]) == {**SPAN_IDS, "$span_id": "hook"} + + +@pytest.mark.asyncio +@pytest.mark.parametrize("method", list(TRACE_CALLS)) +async def test_async_before_send_sees_and_changes_span_ids(method): + seen: list = [] + events = await _async_wire_events( + _capture_in_span(method), + before_send=_span_id_hook(seen), + **_trace_config(None, _trace_context_setting(method)), + ) + assert seen == [SPAN_IDS] + assert _span_ids(events[0]["properties"]) == {**SPAN_IDS, "$span_id": "hook"} + + +GEOIP_CALL_CASES = [ + pytest.param(True, "context", False, True, id="call_beats_context"), + pytest.param(True, "super", False, True, id="call_beats_super"), + pytest.param(False, "super", True, False, id="call_false_beats_super"), + pytest.param(False, None, None, False, id="call_false_beats_client_setting"), + pytest.param(True, "event", False, False, id="event_property_beats_call"), +] + + +def _capture_with_call_geoip(call_value, source, layer_value): + def call(client): + with new_context(fresh=True): + if source == "context": + tag("$geoip_disable", layer_value) + properties = {"$geoip_disable": layer_value} if source == "event" else None + return client.capture( + "e", distinct_id="u", properties=properties, disable_geoip=call_value + ) + + return call + + +def _geoip_layer_config(source, layer_value): + if source == "super": + return {"super_properties": {"$geoip_disable": layer_value}} + return {} + + +@pytest.mark.parametrize("call_value, source, layer_value, expected", GEOIP_CALL_CASES) +def test_sync_call_disable_geoip_is_an_event_value( + call_value, source, layer_value, expected +): + events = _sync_wire_events( + _capture_with_call_geoip(call_value, source, layer_value), + disable_geoip=True, + **_geoip_layer_config(source, layer_value), + ) + assert events[0]["properties"]["$geoip_disable"] is expected + + +@pytest.mark.asyncio +@pytest.mark.parametrize("call_value, source, layer_value, expected", GEOIP_CALL_CASES) +async def test_async_call_disable_geoip_is_an_event_value( + call_value, source, layer_value, expected +): + events = await _async_wire_events( + _capture_with_call_geoip(call_value, source, layer_value), + disable_geoip=True, + **_geoip_layer_config(source, layer_value), + ) + assert events[0]["properties"]["$geoip_disable"] is expected + + +EVERY_PATH_CASES = [ + pytest.param(None, SDK_LIBRARY, id="sdk_library"), + pytest.param(SDK_FLAGS, SDK_FLAGS, id="super_flags"), + pytest.param(CALLER_LIBRARY, CALLER_LIBRARY, id="super_library"), +] + + +@pytest.mark.parametrize("method", list(CAPTURE_CALLS)) +@pytest.mark.parametrize("super_properties, expected", EVERY_PATH_CASES) +def test_sync_super_properties_beat_sdk_values_on_every_path( + method, super_properties, expected +): + events = _sync_wire_events( + lambda c: CAPTURE_CALLS[method](c, None), super_properties=super_properties + ) + _assert_caller_values(events, expected) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("method", list(ASYNC_LIBRARY_CALLS)) +@pytest.mark.parametrize("super_properties, expected", EVERY_PATH_CASES) +async def test_async_super_properties_beat_sdk_values_on_every_path( + method, super_properties, expected +): + events = await _async_wire_events( + lambda c: ASYNC_LIBRARY_CALLS[method](c, None), + super_properties=super_properties, + ) + _assert_caller_values(events, expected) + + +def _library(properties): + return {k: properties[k] for k in SDK_LIBRARY if k in properties} + + +# Layers, lowest first: super, context, event. Only a non-empty string sets +# $lib or $lib_version, so a null, empty or non-string value counts as unset. +LIBRARY_CASES = [ + pytest.param({}, {}, {}, SDK_LIBRARY, id="no_layer"), + pytest.param( + {}, {}, {"$lib": "caller-lib"}, {"$lib": "caller-lib"}, id="caller_lib_alone" + ), + pytest.param( + {}, + {}, + {"$lib": "caller-lib", "$lib_version": None}, + {"$lib": "caller-lib", "$lib_version": None}, + id="caller_lib_keeps_null_version", + ), + pytest.param({}, {}, {"$lib": "posthog-python"}, SDK_LIBRARY, id="sdk_lib_alone"), + pytest.param( + {}, + {}, + {"$lib": "posthog-python", "$lib_version": ""}, + SDK_LIBRARY, + id="sdk_lib_empty_version", + ), + pytest.param( + {}, + {}, + {"$lib": "posthog-python", "$lib_version": 5}, + SDK_LIBRARY, + id="sdk_lib_number_version", + ), + pytest.param({}, {}, {"$lib": " "}, {"$lib": " "}, id="whitespace_lib_is_set"), + pytest.param( + {"$lib": 5, "$lib_version": "super-version"}, + {}, + {}, + SDK_LIBRARY, + id="super_number_lib", + ), + pytest.param( + {}, + {}, + {"$lib": "posthog-python", "$lib_version": "1.0.0"}, + {"$lib": "posthog-python", "$lib_version": "1.0.0"}, + id="sdk_lib_caller_version", + ), + *( + pytest.param({}, {}, {"$lib": value}, SDK_LIBRARY, id=f"{name}_lib") + for name, value in [ + ("null", None), + ("empty", ""), + ("number", 5), + ("bool", True), + ("dict", {}), + ] + ), + pytest.param( + {}, {}, {"$lib_version": "caller-version"}, SDK_LIBRARY, id="lone_version" + ), + pytest.param( + {}, + {}, + {"$lib": None, "$lib_version": "caller-version"}, + SDK_LIBRARY, + id="null_lib_with_version", + ), + pytest.param( + {"$lib_version": "super-version"}, + {}, + {}, + SDK_LIBRARY, + id="super_lone_version", + ), + pytest.param( + CALLER_LIBRARY, {}, {"$lib": None}, CALLER_LIBRARY, id="super_fills_null_lib" + ), + pytest.param( + {}, + {"$lib": "context-lib"}, + {"$lib": ""}, + {"$lib": "context-lib"}, + id="context_fills_empty_lib", + ), + pytest.param( + CALLER_LIBRARY, + {"$lib": "context-lib"}, + {}, + {"$lib": "context-lib", "$lib_version": "caller-version"}, + id="context_beats_super_by_key", + ), + pytest.param( + {"$lib": "super-lib"}, + {}, + {"$lib": "posthog-python"}, + SDK_LIBRARY, + id="event_sdk_lib_beats_super", + ), +] + + +def _library_capture(context, event): + def call(client): + with new_context(fresh=True): + for key, value in context.items(): + tag(key, value) + return client.capture("e", distinct_id="u", properties=dict(event)) + + return call + + +@pytest.mark.parametrize("super_properties, context, event, expected", LIBRARY_CASES) +def test_sync_sdk_library_fills_as_a_pair(super_properties, context, event, expected): + events = _sync_wire_events( + _library_capture(context, event), super_properties=super_properties + ) + assert _library(events[0]["properties"]) == expected + + +@pytest.mark.asyncio +@pytest.mark.parametrize("super_properties, context, event, expected", LIBRARY_CASES) +async def test_async_sdk_library_fills_as_a_pair( + super_properties, context, event, expected +): + events = await _async_wire_events( + _library_capture(context, event), super_properties=super_properties + ) + assert _library(events[0]["properties"]) == expected + + +def _without_library(properties): + return {k: v for k, v in properties.items() if k not in SDK_LIBRARY} + + +LIBRARY_HOOKS = { + "change": ( + lambda p: {**_without_library(p), "$lib": "hook-lib"}, + {"$lib": "hook-lib"}, + ), + "remove": (_without_library, {}), + "null": (lambda p: {**p, "$lib": None}, {**SDK_LIBRARY, "$lib": None}), +} + + +def _library_hook(seen, change): + def hook(msg): + seen.append(_library(msg["properties"])) + return {**msg, "properties": change(msg["properties"])} + + return hook + + +@pytest.mark.parametrize("hook", list(LIBRARY_HOOKS)) +def test_sync_before_send_sees_and_changes_the_sdk_library(hook): + change, expected = LIBRARY_HOOKS[hook] + seen: list = [] + events = _sync_wire_events( + lambda c: c.capture("e", distinct_id="u"), + before_send=_library_hook(seen, change), + ) + assert seen == [SDK_LIBRARY] + assert _library(events[0]["properties"]) == expected + + +@pytest.mark.asyncio +@pytest.mark.parametrize("hook", list(LIBRARY_HOOKS)) +async def test_async_before_send_sees_and_changes_the_sdk_library(hook): + change, expected = LIBRARY_HOOKS[hook] + seen: list = [] + events = await _async_wire_events( + lambda c: c.capture("e", distinct_id="u"), + before_send=_library_hook(seen, change), + ) + assert seen == [SDK_LIBRARY] + assert _library(events[0]["properties"]) == expected + + +@pytest.mark.parametrize("method", ["set", "set_once"]) +def test_set_call_wins_over_super_person_properties(method): + key = f"${method}" + events = _sync_wire_events( + lambda c: getattr(c, method)(distinct_id="u", properties={"plan": "pro"}), + super_properties={key: {"plan": "free", "source": "super"}}, + ) + assert events[0]["properties"][key] == {"plan": "pro", "source": "super"} + + +@pytest.mark.parametrize( + "event, extra", [("e", {}), ("$identify", {PP: True})], ids=["other", "identify"] +) +def test_late_options_replace_and_remove_legacy_properties(event, extra): + def call(client): + with new_context(fresh=True): + set_context_option("product_tour_id", "context-tour") + return client.capture( + event, distinct_id="u", properties={"$product_tour_id": "event-tour"} + ) + + events = _sync_wire_events( + call, + super_properties={"$cookieless_mode": False}, + super_options={"cookieless_mode": True}, + ) + assert events[0]["options"] == { + "cookieless_mode": True, + "product_tour_id": "context-tour", + **extra, + } + assert not {"$cookieless_mode", "$product_tour_id"} & events[0]["properties"].keys() + + +def _personless_ai_capture(client): + with new_context(fresh=True): + set_context_option(PP, True) + return _capture_ai_event( + client, + "$ai_generation", + distinct_id="trace-1", + properties={"$process_person_profile": True}, + options={PP: True, "cookieless_mode": True}, + personless=True, + ) + + +@pytest.mark.parametrize( + "before_send, expected", + [ + (None, {PP: False, "cookieless_mode": True}), + (lambda m: {**m, "options": {PP: True}}, {PP: True}), + ], + ids=["sdk_option_wins", "before_send_can_change_it"], +) +def test_personless_ai_event_overrides_every_user_layer(before_send, expected): + events = _sync_wire_events( + _personless_ai_capture, before_send=before_send, super_options={PP: True} + ) + assert events[0]["options"] == expected + + +MODES = ["sync", "async"] + +# Listed here rather than imported, so the test pins the exact names. +IDENTIFY_STYLE_EVENTS = [ + "$identify", + "$create_alias", + "$merge_dangerously", + "$groupidentify", + "$set", + "$set_once", +] + + +async def _wire_events(mode, call, before_send=None, **config) -> list[dict]: + if mode == "sync": + return _sync_wire_events(call, before_send=before_send, **config) + return await _async_wire_events(call, before_send=before_send, **config) + + +def _capture_as(name, method="capture"): + return lambda c, o, p: getattr(c, method)( + name, distinct_id="u", properties=p, options=o + ) + + +IDENTIFY_STYLE_EMITTERS = { + "set": lambda c, o, p: c.set(distinct_id="u", properties={"a": 1}, options=o), + "set_once": lambda c, o, p: c.set_once( + distinct_id="u", properties={"a": 1}, options=o + ), + "group_identify": lambda c, o, p: c.group_identify( + "company", "acme", distinct_id="u", options=o + ), + "alias": lambda c, o, p: c.alias("previous", "u", options=o), + **{f"capture:{name}": _capture_as(name) for name in IDENTIFY_STYLE_EVENTS}, + "capture_ai:$identify": _capture_as("$identify", "capture_ai"), +} +# Only the capture methods take event properties, so only they can set the +# legacy property on the call. +PROPERTY_EMITTERS = [k for k in IDENTIFY_STYLE_EMITTERS if k.startswith("capture")] + + +def _layers(value): + """Each layer kind that can set person processing, keyed by kind.""" + return { + "super_options": {"super_options": {PP: value}}, + "super_properties": {"super_properties": {LEGACY_PP: value}}, + "context_option": {"context_options": {PP: value}}, + "context_tag": {"tags": {LEGACY_PP: value}}, + } + + +def _all_layers(value): + if value is None: + return {} + return {k: v for layer in _layers(value).values() for k, v in layer.items()} + + +def _layered(emit, layers, options=None, properties=None): + def call(client): + with new_context(fresh=True): + for key, value in layers.get("context_options", {}).items(): + set_context_option(key, value) + for key, value in layers.get("tags", {}).items(): + tag(key, value) + return emit(client, options, properties) + + return call + + +def _client_config(layers): + return {k: layers[k] for k in ("super_options", "super_properties") if k in layers} + + +def _assert_person_processing(events, expected): + assert events[0]["options"][PP] is expected + assert LEGACY_PP not in events[0]["properties"] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("mode", MODES) +@pytest.mark.parametrize("layer", ["no_layer", *_layers(False)]) +@pytest.mark.parametrize("emitter", list(IDENTIFY_STYLE_EMITTERS)) +async def test_identify_style_event_defaults_person_processing_on(mode, layer, emitter): + layers = _layers(False).get(layer, {}) + events = await _wire_events( + mode, + _layered(IDENTIFY_STYLE_EMITTERS[emitter], layers), + **_client_config(layers), + ) + _assert_person_processing(events, True) + + +# (layer value, call options, expected) +CALL_OPTION_CASES = { + "option_false_beats_true_layers": (True, {PP: False}, False), + "option_true_beats_false_layers": (False, {PP: True}, True), + "null_option_is_unset": (False, {PP: None}, True), +} + + +@pytest.mark.asyncio +@pytest.mark.parametrize("mode", MODES) +@pytest.mark.parametrize("case", list(CALL_OPTION_CASES)) +@pytest.mark.parametrize("emitter", list(IDENTIFY_STYLE_EMITTERS)) +async def test_identify_style_event_keeps_the_call_option(mode, case, emitter): + layer_value, options, expected = CALL_OPTION_CASES[case] + layers = _all_layers(layer_value) + events = await _wire_events( + mode, + _layered(IDENTIFY_STYLE_EMITTERS[emitter], layers, options=options), + **_client_config(layers), + ) + _assert_person_processing(events, expected) + + +# (layer value, call options, call properties, expected) +CALL_PROPERTY_CASES = { + "legacy_false_moves_to_option": (None, None, {LEGACY_PP: False}, False), + "legacy_false_beats_true_layers": (True, None, {LEGACY_PP: False}, False), + "legacy_true_beats_false_layers": (False, None, {LEGACY_PP: True}, True), + "option_beats_legacy": (None, {PP: False}, {LEGACY_PP: True}, False), + "null_legacy_is_unset": (False, None, {LEGACY_PP: None}, True), +} + + +@pytest.mark.asyncio +@pytest.mark.parametrize("mode", MODES) +@pytest.mark.parametrize("case", list(CALL_PROPERTY_CASES)) +@pytest.mark.parametrize("emitter", PROPERTY_EMITTERS) +async def test_identify_style_event_takes_the_call_legacy_property(mode, case, emitter): + layer_value, options, properties, expected = CALL_PROPERTY_CASES[case] + layers = _all_layers(layer_value) + events = await _wire_events( + mode, + _layered( + IDENTIFY_STYLE_EMITTERS[emitter], + layers, + options=options, + properties=properties, + ), + **_client_config(layers), + ) + _assert_person_processing(events, expected) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("mode", MODES) +@pytest.mark.parametrize( + "properties, expected", + [(None, False), ({LEGACY_PP: True}, True)], + ids=["personless_default_stays", "call_legacy_wins"], +) +@pytest.mark.parametrize("name", IDENTIFY_STYLE_EVENTS) +async def test_identify_style_event_with_a_generated_distinct_id( + mode, properties, expected, name +): + events = await _wire_events(mode, lambda c: c.capture(name, properties=properties)) + _assert_person_processing(events, expected) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("mode", MODES) +async def test_group_identify_fallback_distinct_id_processes_the_person(mode): + events = await _wire_events(mode, lambda c: c.group_identify("company", "acme")) + assert events[0]["distinct_id"] == "$company_acme" + _assert_person_processing(events, True) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("mode", MODES) +@pytest.mark.parametrize( + "emitter, properties, resolved", + [("alias", None, True), ("capture:$identify", {LEGACY_PP: False}, False)], + ids=["default", "hoisted_legacy"], +) +async def test_before_send_sees_the_resolved_option_and_has_final_say( + mode, emitter, properties, resolved +): + seen: list = [] + + def hook(msg): + seen.append((msg["options"].get(PP), LEGACY_PP in msg["properties"])) + return {**msg, "options": {**msg["options"], PP: not resolved}} + + events = await _wire_events( + mode, + lambda c: IDENTIFY_STYLE_EMITTERS[emitter](c, None, properties), + before_send=hook, + ) + assert seen == [(resolved, False)] + _assert_person_processing(events, not resolved) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("mode", MODES) +@pytest.mark.parametrize("name", ["e", "identify", "$IDENTIFY", "$set_once_extra"]) +async def test_other_events_keep_layered_person_processing(mode, name): + layers = _all_layers(False) + events = await _wire_events( + mode, _layered(_capture_as(name), layers), **_client_config(layers) + ) + _assert_person_processing(events, False) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("mode", MODES) +async def test_before_send_rename_to_identify_style_gets_no_default(mode): + events = await _wire_events( + mode, + lambda c: c.capture("e", distinct_id="u"), + before_send=lambda msg: {**msg, "event": "$identify"}, + super_options={PP: False}, + ) + assert events[0]["event"] == "$identify" + _assert_person_processing(events, False) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("mode", MODES) +@pytest.mark.parametrize( + "emitter, properties, expected", + [("alias", None, True), ("capture:$identify", {LEGACY_PP: False}, False)], + ids=["default", "hoisted_legacy"], +) +async def test_identify_style_default_leaves_the_call_dicts_unchanged( + mode, emitter, properties, expected +): + options = {"cookieless_mode": True} + caller_properties = None if properties is None else dict(properties) + events = await _wire_events( + mode, + lambda c: IDENTIFY_STYLE_EMITTERS[emitter](c, options, caller_properties), + ) + assert options == {"cookieless_mode": True} + assert caller_properties == properties + assert events[0]["options"] == {"cookieless_mode": True, PP: expected} + + +LEGACY_FALSE_LAYERS = ["super_properties", "context_tag"] + + +def _record_person_processing(seen, drop_options=False): + def hook(msg): + seen.append((msg["options"].get(PP), msg["properties"].get(LEGACY_PP, "unset"))) + if drop_options: + return {k: v for k, v in msg.items() if k != "options"} + return msg + + return hook + + +@pytest.mark.asyncio +@pytest.mark.parametrize("mode", MODES) +@pytest.mark.parametrize("layer", LEGACY_FALSE_LAYERS) +@pytest.mark.parametrize("emitter", list(IDENTIFY_STYLE_EMITTERS)) +async def test_before_send_sees_no_layered_legacy_property_on_identify_style_events( + mode, layer, emitter +): + layers = _layers(False)[layer] + seen: list = [] + await _wire_events( + mode, + _layered(IDENTIFY_STYLE_EMITTERS[emitter], layers), + before_send=_record_person_processing(seen), + **_client_config(layers), + ) + assert seen == [(True, "unset")] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("mode", MODES) +@pytest.mark.parametrize("layer", LEGACY_FALSE_LAYERS) +async def test_hook_that_drops_options_sends_no_layered_legacy_false(mode, layer): + layers = _layers(False)[layer] + events = await _wire_events( + mode, + _layered(IDENTIFY_STYLE_EMITTERS["alias"], layers), + before_send=_record_person_processing([], drop_options=True), + **_client_config(layers), + ) + assert PP not in events[0]["options"] + assert LEGACY_PP not in events[0]["properties"] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("mode", MODES) +@pytest.mark.parametrize("layer", LEGACY_FALSE_LAYERS) +async def test_before_send_still_sees_the_layered_legacy_property_on_other_events( + mode, layer +): + layers = {**_layers(False)[layer], "super_options": {PP: True}} + seen: list = [] + events = await _wire_events( + mode, + _layered(_capture_as("e"), layers), + before_send=_record_person_processing(seen), + **_client_config(layers), + ) + assert seen == [(True, False)] + _assert_person_processing(events, True) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("mode", MODES) +@pytest.mark.parametrize("layer", ["super_options", "context_option"]) +@pytest.mark.parametrize("name", IDENTIFY_STYLE_EVENTS) +async def test_option_layers_still_fill_identify_style_events_with_a_generated_id( + mode, layer, name +): + layers = _layers(True)[layer] + events = await _wire_events( + mode, + _layered(lambda c, o, p: c.capture(name), layers), + **_client_config(layers), + ) + _assert_person_processing(events, True) diff --git a/posthog/test/test_exception_capture.py b/posthog/test/test_exception_capture.py index 1485ffff9..6422a92d9 100644 --- a/posthog/test/test_exception_capture.py +++ b/posthog/test/test_exception_capture.py @@ -107,7 +107,7 @@ def test_nan_limiter_configuration_keeps_exception_hook_working( previous_hook = MagicMock() upload = MagicMock() monkeypatch.setattr(sys, "excepthook", previous_hook) - monkeypatch.setattr("posthog.client.batch_post", upload) + monkeypatch.setattr("posthog.client._send_v1_batch", upload) options = { "exception_autocapture_bucket_size": 3, "exception_autocapture_refill_interval_seconds": 60, @@ -331,15 +331,10 @@ def test_excepthook(tmpdir): dedent( """ from posthog import Posthog - from requests import Response import posthog.request + from posthog.test.capture_helpers import offline_v1_post - def offline_post(url, **kwargs): - response = Response() - response.status_code = 200 - return response - - posthog.request._session.post = offline_post + posthog.request._capture_session.post = offline_v1_post posthog = Posthog('phc_x', host='https://eu.i.posthog.com', enable_exception_autocapture=True, debug=True, on_error=lambda e, batch: print('error handling batch: ', e, batch)) # frame_value = "LOL" @@ -358,7 +353,9 @@ def offline_post(url, **kwargs): assert b"ZeroDivisionError" in output assert b"LOL" in output - assert b"DEBUG:posthog:[PostHog] data uploaded successfully" in output + assert b"[PostHog] capture v1 response" in output + assert b" ok=1 " in output + assert b'"type": "ZeroDivisionError", "value": "division by zero"' in output assert b'"$exception_level": "fatal"' in output assert b'"$exception_source": "python.sys_excepthook"' in output assert b'"type": "onuncaughtexception"' in output diff --git a/posthog/test/test_experiment_exposure.py b/posthog/test/test_experiment_exposure.py index 062f90e46..6148aa460 100644 --- a/posthog/test/test_experiment_exposure.py +++ b/posthog/test/test_experiment_exposure.py @@ -1523,14 +1523,16 @@ def before_send(message: Dict[str, Any]) -> Optional[Dict[str, Any]]: return None if message["event"] == EXPOSURE else message async def batch_post(*args: Any, **kwargs: Any) -> None: - batches.append(kwargs["batch"]) + batches.append(args[2] if len(args) > 2 else kwargs["batch"]) with ( mock.patch( "posthog.async_client._async_flags", new=mock.AsyncMock(return_value=_response(_split())), ), - mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post), + mock.patch( + "posthog._async_consumer.async_send_v1_batch", side_effect=batch_post + ), ): client = AsyncPosthog("project-key", before_send=before_send, flush_interval=30) for _ in range(2): @@ -1665,13 +1667,13 @@ def test_a_read_during_a_sync_mode_send_does_not_send_it_again(delivered): # The second read runs while the first read's exposure is on the wire. It sends # neither event. A send that fails releases the key, so a third read sends the # exposure. - client = Client(FAKE_TEST_API_KEY, sync_mode=True, capture_mode="v0") + client = Client(FAKE_TEST_API_KEY, sync_mode=True) sending = threading.Event() finish = threading.Event() posted: List[str] = [] - def batch_post(*args: Any, batch: List[Dict[str, Any]], **kwargs: Any) -> None: - [message] = batch + def batch_post(*args: Any, **kwargs: Any) -> None: + [message] = args[2] if len(args) > 2 else kwargs["batch"] posted.append(message["event"]) if message["event"] == EXPOSURE and posted.count(EXPOSURE) == 1: sending.set() @@ -1682,7 +1684,7 @@ def batch_post(*args: Any, batch: List[Dict[str, Any]], **kwargs: Any) -> None: try: with ( _serving(_response(_split())), - mock.patch("posthog.client.batch_post", side_effect=batch_post), + mock.patch("posthog.client._send_v1_batch", side_effect=batch_post), ): first = threading.Thread(target=_read, args=(client, "get_feature_flag")) first.start() @@ -1753,7 +1755,9 @@ def _flag_identity(properties: Mapping[str, Any]) -> Dict[str, Any]: } -def _messages_with_super_properties(record: Dict[str, Any]) -> List[Dict[str, Any]]: +def _messages_with_super_properties( + record: Dict[str, Any], super_properties: Optional[Dict[str, Any]] = None +) -> List[Dict[str, Any]]: messages: List[Dict[str, Any]] = [] def before_send(message: Dict[str, Any]) -> Dict[str, Any]: @@ -1764,7 +1768,9 @@ def before_send(message: Dict[str, Any]) -> Dict[str, Any]: FAKE_TEST_API_KEY, send=False, before_send=before_send, - super_properties=dict(SPOOFED_SUPER_PROPERTIES), + super_properties=dict( + SPOOFED_SUPER_PROPERTIES if super_properties is None else super_properties + ), ) try: with _serving(_response(record)): @@ -1816,32 +1822,42 @@ def test_super_properties_cannot_add_rule_fields_a_config_version_2_call_omits() def test_super_properties_still_apply_to_config_version_1_calls(): record = _record("condition_match", "annual", config_version=1) [called] = _messages_with_super_properties(record) + [own] = _messages_with_super_properties(record, super_properties={}) + # Nothing is pinned: super properties fill every key the event leaves unset, + # and the event's own values win, as on every event since 8.0. + filled = [ + name for name in SPOOFED_SUPER_PROPERTIES if name not in own["properties"] + ] + assert filled for name, value in SPOOFED_SUPER_PROPERTIES.items(): - assert called["properties"][name] == value, name + expected = own["properties"].get(name, value) + assert called["properties"][name] == expected, name async def test_async_super_properties_cannot_change_config_version_2_attribution(): messages: List[Dict[str, Any]] = [] - with mock.patch( - "posthog.async_client._async_flags", - new=mock.AsyncMock(return_value=_response(_split())), + + # Super properties and the pinned attribution fill in before before_send. + def before_send(message: Dict[str, Any]) -> Dict[str, Any]: + messages.append(copy.deepcopy(message)) + return message + + with ( + mock.patch( + "posthog.async_client._async_flags", + new=mock.AsyncMock(return_value=_response(_split())), + ), + mock.patch("posthog._async_consumer.async_send_v1_batch", new=mock.AsyncMock()), ): client = AsyncPosthog( "project-key", - send=False, + before_send=before_send, super_properties=dict(SPOOFED_SUPER_PROPERTIES), ) - prepare = client._prepare_event - - def record(*args: Any, **kwargs: Any) -> Any: - prepared, uuid = prepare(*args, **kwargs) - messages.append(copy.deepcopy(prepared)) - return prepared, uuid - - with mock.patch.object(client, "_prepare_event", side_effect=record): - snapshot = await client.evaluate_flags(DISTINCT_ID) - snapshot.get_flag(FLAG) + snapshot = await client.evaluate_flags(DISTINCT_ID) + snapshot.get_flag(FLAG) + await client.flush(timeout_seconds=1) await client.shutdown() [called] = [m for m in messages if m["event"] == FLAG_CALLED] diff --git a/posthog/test/test_failed_flag_records.py b/posthog/test/test_failed_flag_records.py index c6ec36582..f17c6ede2 100644 --- a/posthog/test/test_failed_flag_records.py +++ b/posthog/test/test_failed_flag_records.py @@ -198,9 +198,11 @@ def test_filtered_snapshot_preserves_selected_failure_diagnostics( client.capture("filtered-snapshot", distinct_id="user", flags=filtered) enriched = enqueue.call_args.args[0] assert enriched["event"] == "filtered-snapshot" - assert enriched["properties"]["$feature/off"] is False - assert "$feature/failed" not in enriched["properties"] - assert "$feature/other-failed" not in enriched["properties"] + # v1 passes snapshot flag properties to _enqueue separately. + flag_properties = enqueue.call_args.kwargs["flag_properties"] + assert flag_properties["$feature/off"] is False + assert "$feature/failed" not in flag_properties + assert "$feature/other-failed" not in flag_properties assert enqueue.call_count == 2 assert filtered.get_flag("other-failed") is None diff --git a/posthog/test/test_feature_flag_called_minimization.py b/posthog/test/test_feature_flag_called_minimization.py index 9a23e6b17..2106ae778 100644 --- a/posthog/test/test_feature_flag_called_minimization.py +++ b/posthog/test/test_feature_flag_called_minimization.py @@ -13,10 +13,13 @@ from parameterized import parameterized +from posthog.capture_event import _to_v1_event from posthog.client import _MINIMAL_FLAG_CALLED_EVENT_PROPERTIES, Client from posthog.request import GetResponse +from posthog.test.capture_helpers import record_sync_capture_sends from posthog.test.test_utils import FAKE_TEST_API_KEY from posthog.utils import system_context +from posthog.version import VERSION def _flags_response(has_experiment, gate): @@ -64,21 +67,15 @@ def _local_flag_definition(has_experiment): class _CapturedEventsMixin: - """Builds a non-sending client whose fully-enriched events are captured via - ``before_send``, so tests assert the exact wire shape after every enrichment - step (system context, super properties, $lib, ...).""" + """Builds a sync client whose fully-enriched events are recorded at upload, + so tests assert the exact wire shape after every enrichment step (system + context, super properties, $lib, ...).""" def _make_client(self, **kwargs): - captured = [] - - def before_send(msg): - captured.append(msg) - return msg - + captured = record_sync_capture_sends(self) client = Client( FAKE_TEST_API_KEY, - send=False, - before_send=before_send, + sync_mode=True, super_properties={"app_version": "1.2.3"}, **kwargs, ) @@ -89,6 +86,12 @@ def _flag_called_properties(self, captured, index=0): assert events, "no $feature_flag_called event captured" return events[index]["properties"] + def _assert_wire_sdk_library(self, captured): + events = [m for m in captured if m["event"] == "$feature_flag_called"] + properties = _to_v1_event(events[0])["properties"] + self.assertEqual(properties["$lib"], "posthog-python") + self.assertEqual(properties["$lib_version"], VERSION) + class TestMinimizationViaFlagsResponse(_CapturedEventsMixin, unittest.TestCase): """Gate sourced from the top-level ``minimalFlagCalledEvents`` field of the v2 @@ -125,6 +128,7 @@ def test_gated_non_experiment_flag_sends_exactly_the_allowlist(self, patch_flags | set(system_context()), ) self.assertLessEqual(set(properties), _MINIMAL_FLAG_CALLED_EVENT_PROPERTIES) + self._assert_wire_sdk_library(captured) self.assertIs(properties["$is_server"], True) self.assertEqual(properties["$feature_flag"], "person-flag") self.assertEqual(properties["$feature_flag_response"], True) @@ -153,6 +157,34 @@ def test_gated_non_experiment_flag_with_groups_keeps_group_context( self.assertEqual(properties["$groups"], {"organization": "org-1"}) self.assertLessEqual(set(properties), _MINIMAL_FLAG_CALLED_EVENT_PROPERTIES) + @mock.patch("posthog.client.flags") + def test_gated_event_keeps_option_sources(self, patch_flags): + patch_flags.return_value = _flags_response(has_experiment=False, gate=True) + client, captured = self._make_client() + client.super_properties = { + "$cookieless_mode": True, + "$ignore_sent_at": True, + "$product_tour_id": "tour-1", + "$window_id": "w-1", + "app_version": "1.2.3", + } + + client.get_feature_flag_result("person-flag", "some-distinct-id") + + event = _to_v1_event( + next(m for m in captured if m["event"] == "$feature_flag_called") + ) + self.assertEqual( + event["options"], + { + "cookieless_mode": True, + "disable_skew_correction": True, + "product_tour_id": "tour-1", + }, + ) + self.assertEqual(event["window_id"], "w-1") + self.assertNotIn("app_version", event["properties"]) + @mock.patch("posthog.client.flags") def test_remote_evaluation_uses_this_responses_gate_not_a_concurrent_update( self, patch_flags @@ -308,6 +340,7 @@ def test_gated_non_experiment_flag_sends_exactly_the_allowlist( | set(system_context()), ) self.assertLessEqual(set(properties), _MINIMAL_FLAG_CALLED_EVENT_PROPERTIES) + self._assert_wire_sdk_library(captured) self.assertEqual(properties["$feature_flag_response"], True) self.assertIs(properties["locally_evaluated"], True) @@ -509,6 +542,7 @@ def test_gated_non_experiment_flag_sends_exactly_the_allowlist(self, patch_flags | set(system_context()), ) self.assertLessEqual(set(properties), _MINIMAL_FLAG_CALLED_EVENT_PROPERTIES) + self._assert_wire_sdk_library(captured) self.assertEqual(properties["$feature_flag_response"], "variant-value") self.assertIs(properties["$feature_flag_has_experiment"], False) diff --git a/posthog/test/test_flag_definition_cache.py b/posthog/test/test_flag_definition_cache.py index 2d05997d4..d221245d9 100644 --- a/posthog/test/test_flag_definition_cache.py +++ b/posthog/test/test_flag_definition_cache.py @@ -17,6 +17,7 @@ ) from posthog.request import GetResponse from posthog.test.test_utils import FAKE_TEST_API_KEY +from posthog.test.capture_helpers import patch_capture_send class MockCacheProvider: @@ -94,8 +95,8 @@ class TestFlagDefinitionCacheProvider(unittest.TestCase): @classmethod def setUpClass(cls): # Prevent real HTTP requests - cls.client_post_patcher = mock.patch("posthog.client.batch_post") - cls.consumer_post_patcher = mock.patch("posthog.consumer.batch_post") + cls.client_post_patcher = patch_capture_send("client") + cls.consumer_post_patcher = patch_capture_send("consumer") cls.client_post_patcher.start() cls.consumer_post_patcher.start() diff --git a/posthog/test/test_flags_v4_response.py b/posthog/test/test_flags_v4_response.py index c730f54f5..ee5c367bf 100644 --- a/posthog/test/test_flags_v4_response.py +++ b/posthog/test/test_flags_v4_response.py @@ -1148,15 +1148,17 @@ def _legacy_outputs(shape: str) -> Dict[str, Any]: def response(*args: Any, **kwargs: Any) -> Dict[str, Any]: return _parity_response(shape) - def enqueue(message: Dict[str, Any], *args: Any, **kwargs: Any) -> Optional[str]: + # Read the built event in before_send: v1 layers flag properties inside _enqueue. + def record(message: Dict[str, Any]) -> Optional[Dict[str, Any]]: events.append((message["event"], _flag_event_properties(message))) - # Accept the event, as the real queue does, by returning an event UUID. - return "70000000-0000-4000-8000-000000000000" + # Keep the event, so capture accepts it and returns its UUID as the real + # queue does; flag events dedupe only events that were accepted. + return message try: with ( mock.patch("posthog.client.flags", side_effect=response), - mock.patch.object(client, "_enqueue", side_effect=enqueue), + mock.patch.object(client, "before_send", record), pytest.warns(DeprecationWarning), ): outputs["get_feature_variants"] = client.get_feature_variants(DISTINCT_ID) diff --git a/posthog/test/test_gevent_compat.py b/posthog/test/test_gevent_compat.py index 34e0655bf..2948e9b2c 100644 --- a/posthog/test/test_gevent_compat.py +++ b/posthog/test/test_gevent_compat.py @@ -10,6 +10,7 @@ from posthog.client import Client, _new_lane_queue from posthog.test.test_utils import FAKE_TEST_API_KEY +from posthog.test.capture_helpers import patch_capture_send class TestLaneQueueFallback(unittest.TestCase): @@ -80,7 +81,7 @@ def test_incompatible_queue_does_not_disable_queue_independent_capabilities(self with ( mock.patch("posthog.client.Queue", return_value=incompatible_queue), mock.patch.dict(sys.modules, {"gevent.monkey": None}), - mock.patch("posthog.client.batch_post") as mock_post, + patch_capture_send("client") as mock_post, mock.patch( "posthog.client.flags", return_value={"featureFlags": {"beta-feature": True}}, @@ -113,9 +114,9 @@ def test_capture_and_flush_after_monkey_patching(self): "is not being exercised" ) - from unittest import mock + from posthog.test.capture_helpers import patch_capture_send - with mock.patch("posthog.consumer.batch_post") as mock_post: + with patch_capture_send("consumer") as mock_post: from posthog.client import Client client = Client("phc_test", flush_at=1, flush_interval=60) @@ -137,7 +138,7 @@ def test_capture_and_flush_after_monkey_patching(self): client.flush(timeout_seconds=10) client.join() - assert mock_post.called, "batch_post was never called" + assert mock_post.called, "capture send was never called" assert client.queue.empty(), "flush did not drain the queue" """ ) diff --git a/posthog/test/test_module.py b/posthog/test/test_module.py index dc875e674..e9d634dc3 100644 --- a/posthog/test/test_module.py +++ b/posthog/test/test_module.py @@ -7,6 +7,7 @@ import posthog from posthog import Posthog +from posthog.test.capture_helpers import patch_capture_send, sent_batch class TestModule(unittest.TestCase): @@ -17,7 +18,7 @@ def _assert_enqueue_result(self, result): self.assertTrue(result) def setUp(self): - patcher = mock.patch("posthog.consumer.batch_post") + patcher = patch_capture_send("consumer") self.transport = patcher.start() self.addCleanup(patcher.stop) self.on_error = mock.Mock() @@ -32,7 +33,7 @@ def test_track(self): self._assert_enqueue_result(res) self.posthog.flush() self.transport.assert_called_once() - event = self.transport.call_args.kwargs["batch"][0] + event = sent_batch(self.transport)[0] self.assertEqual(event["event"], "python module event") self.assertEqual(event["distinct_id"], "distinct_id") self.assertEqual(event["uuid"], res) @@ -42,7 +43,7 @@ def test_alias(self): self._assert_enqueue_result(res) self.posthog.flush() self.transport.assert_called_once() - event = self.transport.call_args.kwargs["batch"][0] + event = sent_batch(self.transport)[0] self.assertEqual(event["event"], "$create_alias") self.assertEqual(event["distinct_id"], "previousId") self.assertEqual(event["properties"]["alias"], "distinct_id") @@ -57,6 +58,15 @@ def test_module_flush_forwards_timeout(self): proxy.assert_called_once_with("flush", timeout_seconds=1.5) + def test_module_capture_exception_forwards_level(self): + error = ValueError("boom") + with mock.patch.object(posthog, "_proxy") as proxy: + posthog.capture_exception(error, level="warning") + + proxy.assert_called_once_with( + "capture_exception", exception=error, level="warning" + ) + class TestModuleLevelSetup(unittest.TestCase): def setUp(self): @@ -64,6 +74,7 @@ def setUp(self): self._original_api_key = posthog.api_key self._original_project_api_key = posthog.project_api_key self._original_project_root = posthog.project_root + self._original_super_options = posthog.super_options self._original_privacy_mode = posthog.privacy_mode self._original_disabled = posthog.disabled self._original_send = posthog.send @@ -80,6 +91,7 @@ def tearDown(self): posthog.api_key = self._original_api_key posthog.project_api_key = self._original_project_api_key posthog.project_root = self._original_project_root + posthog.super_options = self._original_super_options posthog.privacy_mode = self._original_privacy_mode posthog.disabled = self._original_disabled posthog.send = self._original_send @@ -103,6 +115,23 @@ def test_setup_configures_disabled_client_when_api_key_is_blank( self.assertTrue(client.disabled) self.assertIsNone(posthog.capture("Module Python Event", distinct_id="john")) + @parameterized.expand( + [ + ("api_key", "api_key"), + ("project_api_key", "project_api_key"), + ] + ) + def test_setup_keeps_client_disabled_for_personal_api_key(self, _name, setting): + setattr(posthog, setting, " phx_not_a_real_key ") + + client = posthog.setup() + + # Module calls re-run setup(), which must not re-enable the client. + self.assertIsNone(posthog.capture("Module Python Event", distinct_id="john")) + self.assertIsNone(posthog.capture("Module Python Event", distinct_id="john")) + self.assertIs(client, posthog.default_client) + self.assertTrue(client.disabled) + def test_setup_uses_project_api_key_when_api_key_is_unset(self): posthog.project_api_key = " phc_project_key " @@ -128,13 +157,19 @@ def test_setup_uses_api_key_when_project_api_key_is_blank(self): self.assertEqual(client.api_key, "phc_api_key") self.assertFalse(client.disabled) - def test_setup_propagates_project_root(self): + @parameterized.expand( + [ + ("project_root", "/path/to/project"), + ("super_options", {"cookieless_mode": True}), + ] + ) + def test_setup_propagates_config(self, setting, value): posthog.api_key = "phc_test" - posthog.project_root = "/path/to/project" + setattr(posthog, setting, value) client = posthog.setup() - self.assertEqual(client.project_root, "/path/to/project") + self.assertEqual(getattr(client, setting), value) def test_setup_propagates_and_updates_privacy_mode(self): posthog.api_key = "phc_test" @@ -168,6 +203,7 @@ def test_group_identify_propagates_distinct_id(self): "company_123", {"name": "Awesome Inc."}, distinct_id="user_456", + options={"cookieless_mode": True}, ) self.mock_client.group_identify.assert_called_once_with( group_type="company", @@ -177,6 +213,7 @@ def test_group_identify_propagates_distinct_id(self): uuid=None, disable_geoip=None, distinct_id="user_456", + options={"cookieless_mode": True}, ) def test_group_identify_distinct_id_defaults_to_none(self): diff --git a/posthog/test/test_reference_markdown.py b/posthog/test/test_reference_markdown.py index bba347504..74505afcb 100644 --- a/posthog/test/test_reference_markdown.py +++ b/posthog/test/test_reference_markdown.py @@ -65,3 +65,24 @@ def test_summaries_keep_the_whole_first_paragraph(pkg): generator.clean(cls) md = generator.entry(cls, "FeatureFlagEvaluations") assert "on the first access per (distinct_id, flag, value) tuple" in md + + +def test_one_migration_guide_titles_the_page_with_its_h1(): + head, body = generator.migration_page( + ["# Migrate the Python SDK from 7.x.x to 8.0.0\n\nIntro."] + ) + assert 'title: "Migrate the Python SDK from 7.x.x to 8.0.0"' in head + assert body == "Intro." + + +def test_several_migration_guides_keep_their_h1s(): + head, *guides = generator.migration_page(["# Guide 2\n\nB.", "# Guide 1\n\nA."]) + assert 'title: "PostHog Python SDK migration guides"' in head + assert guides == ["# Guide 2\n\nB.", "# Guide 1\n\nA."] + + +@pytest.mark.parametrize("major, pin", [(7, '"posthog>=7,<8"'), (8, '"posthog>=8,<9"')]) +def test_getting_started_pins_the_install_to_the_page_major(major, pin): + text = generator.getting_started(major) + assert f"pip install {pin}" in text + assert "{major}" not in text and "{next_major}" not in text diff --git a/posthog/test/test_release_id.py b/posthog/test/test_release_id.py index 12b8e7e24..8d72a12bf 100644 --- a/posthog/test/test_release_id.py +++ b/posthog/test/test_release_id.py @@ -10,6 +10,10 @@ from posthog.client import _MINIMAL_FLAG_CALLED_EVENT_PROPERTIES, Client from posthog.release_id import RELEASE_ID_ENV_VAR, _resolve_release_id from posthog.test.test_utils import FAKE_TEST_API_KEY +from posthog.test.capture_helpers import ( + patch_async_capture_send, + record_sync_capture_sends, +) # (name, call, expected event): one row per public event-producing method, shared # by the sync and async clients. Each call builds its own arguments, because a @@ -79,17 +83,10 @@ def test_env_var_resolution(self, _name, env_value, expected) -> None: class TestClientReleaseId(unittest.TestCase): def _client(self, env_value, **kwargs): - """Build a client under `env_value` and collect the events it would send.""" - events = [] - - def before_send(msg): - events.append(msg) - return msg - + """Build a client under `env_value` and collect the events it sends.""" + events = record_sync_capture_sends(self) with _release_id_env(env_value): - client = Client( - FAKE_TEST_API_KEY, send=False, before_send=before_send, **kwargs - ) + client = Client(FAKE_TEST_API_KEY, sync_mode=True, **kwargs) return client, events @parameterized.expand(EVENT_CALLS) @@ -155,10 +152,10 @@ async def _async_events(env_value, send_events): """Build an async client under `env_value`, run `send_events`, return the batch.""" batches = [] - async def batch_post(*args, **kwargs): - batches.append(kwargs["batch"]) + async def send_batch(api_key, host, batch, **kwargs): + batches.append(batch) - with mock.patch("posthog._async_consumer.async_batch_post", side_effect=batch_post): + with patch_async_capture_send(side_effect=send_batch): with _release_id_env(env_value): client = AsyncPosthog("test-key", flush_interval=30) async with client: diff --git a/posthog/test/test_request.py b/posthog/test/test_request.py index d9d44df79..c93db997a 100644 --- a/posthog/test/test_request.py +++ b/posthog/test/test_request.py @@ -1,8 +1,6 @@ -import gzip import json import socket import unittest -import zlib from datetime import date, datetime, timedelta from unittest import mock from uuid import UUID @@ -20,7 +18,6 @@ KEEP_ALIVE_SOCKET_OPTIONS, QuotaLimitError, _mask_tokens_in_url, - batch_post, determine_server_host, disable_connection_reuse, enable_keep_alive, @@ -134,47 +131,6 @@ def test_message_only_debug_logs_include_posthog_prefix(): class TestRequests(unittest.TestCase): - def test_valid_request(self): - response = requests.Response() - response.status_code = 200 - session = mock.Mock() - session.post.return_value = response - batch = [ - {"distinct_id": "distinct_id", "event": "python event", "type": "track"} - ] - - res = batch_post(TEST_API_KEY, batch=batch, session=session) - - self.assertIs(res, response) - session.post.assert_called_once() - self.assertTrue(session.post.call_args.args[0].endswith("/batch/")) - body = json.loads(session.post.call_args.kwargs["data"]) - self.assertEqual(body["batch"], batch) - self.assertEqual(body["api_key"], TEST_API_KEY) - - def test_invalid_request_error(self): - response = requests.Response() - response.status_code = 400 - response._content = b'{"detail": "Invalid batch"}' - session = mock.Mock() - session.post.return_value = response - - with self.assertRaises(APIError) as raised: - batch_post("testsecret", batch=[], session=session) - - self.assertEqual(raised.exception.status, 400) - self.assertEqual(raised.exception.message, "Invalid batch") - session.post.assert_called_once() - - def test_invalid_host(self): - self.assertRaises( - requests.exceptions.MissingSchema, - batch_post, - "testsecret", - "t.posthog.com/", - batch=[], - ) - def test_post_without_path_preserves_type_error(self): mock_session = mock.MagicMock() @@ -187,7 +143,7 @@ def test_post_without_path_preserves_type_error(self): mock_session.post.assert_not_called() - def test_post_sends_string_payload_without_gzip(self): + def test_post_sends_string_payload(self): mock_response = requests.Response() mock_response.status_code = 200 mock_session = mock.MagicMock() @@ -207,54 +163,6 @@ def test_post_sends_string_payload_without_gzip(self): self.assertEqual(url, "https://test.posthog.com/batch/") self.assertIsInstance(data, str) - def test_post_sends_bytes_payload_with_gzip(self): - mock_response = requests.Response() - mock_response.status_code = 200 - mock_session = mock.MagicMock() - mock_session.post.return_value = mock_response - - request_module.post( - TEST_API_KEY, - host="https://test.posthog.com", - path="/batch/", - gzip=True, - session=mock_session, - batch=[], - ) - - data = mock_session.post.call_args.kwargs["data"] - headers = mock_session.post.call_args.kwargs["headers"] - self.assertIsInstance(data, bytes) - self.assertEqual(headers["Content-Encoding"], "gzip") - body = json.loads(gzip.decompress(data)) - self.assertEqual(body["batch"], []) - self.assertEqual(body["api_key"], TEST_API_KEY) - - def test_post_falls_back_to_uncompressed_payload_when_gzip_fails(self): - for compression_error in [OSError("boom"), zlib.error("boom")]: - with self.subTest(compression_error=type(compression_error)): - mock_response = requests.Response() - mock_response.status_code = 200 - mock_session = mock.MagicMock() - mock_session.post.return_value = mock_response - - with mock.patch.object( - request_module, "GzipFile", side_effect=compression_error - ): - request_module.post( - TEST_API_KEY, - host="https://test.posthog.com", - path="/batch/", - gzip=True, - session=mock_session, - batch=[], - ) - - data = mock_session.post.call_args.kwargs["data"] - headers = mock_session.post.call_args.kwargs["headers"] - self.assertIsInstance(data, str) - self.assertNotIn("Content-Encoding", headers) - def test_datetime_serialization(self): data = {"created": datetime(2012, 3, 4, 5, 6, 7, 891011)} result = json.dumps(data, cls=DatetimeSerializer) @@ -272,30 +180,6 @@ def test_uuid_serialization(self): result = json.dumps(data, cls=DatetimeSerializer) self.assertEqual(result, '{"id": "12345678-1234-5678-1234-567812345678"}') - def test_should_not_timeout(self): - response = requests.Response() - response.status_code = 200 - session = mock.Mock() - session.post.return_value = response - - self.assertIs( - batch_post(TEST_API_KEY, batch=[], timeout=7, session=session), response - ) - session.post.assert_called_once() - self.assertEqual(session.post.call_args.kwargs["timeout"], 7) - - def test_should_timeout(self): - error = requests.ReadTimeout("response deadline exceeded") - session = mock.Mock() - session.post.side_effect = error - - with self.assertRaises(requests.ReadTimeout) as raised: - batch_post("key", batch=[], timeout=1, session=session) - - self.assertIs(raised.exception, error) - session.post.assert_called_once() - self.assertEqual(session.post.call_args.kwargs["timeout"], 1) - def test_quota_limited_flags_response(self): mock_response = requests.Response() mock_response.status_code = 200 @@ -541,10 +425,13 @@ def test_routing_to_custom_host(host, expected): def test_enable_keep_alive_sets_socket_options(): try: enable_keep_alive() - from posthog.request import _session - - adapter = _session.get_adapter("https://example.com") - assert adapter.socket_options == KEEP_ALIVE_SOCKET_OPTIONS + for session in ( + request_module._get_session(), + request_module._get_flags_session(), + request_module._get_capture_session(), + ): + adapter = session.get_adapter("https://example.com") + assert adapter.socket_options == KEEP_ALIVE_SOCKET_OPTIONS finally: set_socket_options(None) @@ -585,12 +472,14 @@ def test_set_socket_options_is_idempotent(): class TestFlagsSession(unittest.TestCase): """Tests for flags session configuration.""" - def test_flags_session_disables_adapter_retries(self): - """HTTP adapter retries are disabled; flags() handles bounded retries.""" - from posthog.request import _build_flags_session - - session = _build_flags_session() - adapter = session.get_adapter("https://test.posthog.com") + @parameterized.expand( + [ + ("flags", request_module._get_flags_session), + ("capture", request_module._get_capture_session), + ] + ) + def test_session_disables_adapter_retries(self, _name, get_session): + adapter = get_session().get_adapter("https://test.posthog.com") retry = adapter.max_retries self.assertEqual(retry.total, 0) @@ -900,6 +789,33 @@ def test_post_serializes_non_finite_floats_as_null(): assert props["ok"] == 1.5 -def test_datetime_serializer_keeps_finite_values(): - body = {"n": 1.5, "s": "x", "b": True, "i": 3, "none": None} - assert json.loads(json.dumps(body, cls=DatetimeSerializer)) == body +@pytest.mark.parametrize("allow_nan", [False, True]) +@pytest.mark.parametrize( + "body, expected", + [ + ( + {"n": 1.5, "s": "x", "b": True, "none": None, "t": (1, 2.5)}, + '{"n": 1.5, "s": "x", "b": true, "none": null, "t": [1, 2.5]}', + ), + ( + {"n": float("nan"), "l": [float("inf"), (float("-inf"), 2.5)]}, + '{"n": null, "l": [null, [null, 2.5]]}', + ), + ], +) +def test_datetime_serializer_writes_non_finite_floats_as_null( + body, expected, allow_nan +): + assert json.dumps(body, cls=DatetimeSerializer, allow_nan=allow_nan) == expected + + +def test_datetime_serializer_copies_only_events_with_non_finite_floats(): + with mock.patch.object( + request_module, + "_replace_non_finite_floats", + wraps=request_module._replace_non_finite_floats, + ) as copy: + json.dumps({"n": [1.5]}, cls=DatetimeSerializer, allow_nan=False) + copy.assert_not_called() + json.dumps({"n": [float("nan")]}, cls=DatetimeSerializer, allow_nan=False) + copy.assert_called() diff --git a/posthog/test/test_server_payload_snapshots.py b/posthog/test/test_server_payload_snapshots.py index 2874e0761..b0bbb0528 100644 --- a/posthog/test/test_server_payload_snapshots.py +++ b/posthog/test/test_server_payload_snapshots.py @@ -29,6 +29,16 @@ def _successful_response() -> requests.Response: return response +def _capture_ok_response(url, data=None, **kwargs) -> requests.Response: + response = requests.Response() + response.status_code = 200 + uuids = [event["uuid"] for event in json.loads(data)["batch"]] + response._content = json.dumps( + {"results": {uuid: {"result": "ok"} for uuid in uuids}} + ).encode() + return response + + def _has_test_file_suffix(value: str) -> bool: return value.replace("\\", "/").endswith(_TEST_FILE_SUFFIX) @@ -43,8 +53,10 @@ def _normalize_snapshot_value(value): for key, item in value.items(): if key == "$lib_version": normalized[key] = "" + elif key == "PostHog-Request-Id": + normalized[key] = "" elif ( - key == "User-Agent" + key in ("User-Agent", "PostHog-Sdk-Info") and isinstance(item, str) and _USER_AGENT_PATTERN.fullmatch(item) ): @@ -99,19 +111,18 @@ def _assert_json_snapshot(name: str, value) -> None: assert actual == expected -def _legacy_event_family_request(): +def _event_family_request(): session = mock.MagicMock() - session.post.return_value = _successful_response() + session.post.side_effect = _capture_ok_response with ( freeze_time(_FIXED_TIME), - mock.patch("posthog.request._get_session", return_value=session), + mock.patch("posthog.capture_send._get_capture_session", return_value=session), mock.patch("posthog.client.system_context", return_value=_RUNTIME_CONTEXT), ): client = Client( "phc_snapshot_project", host="https://example.posthog.test", - capture_mode="v0", flush_at=100, flush_interval=100, ) @@ -167,18 +178,17 @@ def _raise_snapshot_exception() -> None: def _exception_request(): session = mock.MagicMock() - session.post.return_value = _successful_response() + session.post.side_effect = _capture_ok_response with ( freeze_time(_FIXED_TIME), - mock.patch("posthog.request._get_session", return_value=session), + mock.patch("posthog.capture_send._get_capture_session", return_value=session), mock.patch("posthog.client.system_context", return_value=_RUNTIME_CONTEXT), mock.patch("posthog.client._get_current_otel_span_properties", return_value={}), ): client = Client( "phc_snapshot_project", host="https://example.posthog.test", - capture_mode="v0", sync_mode=True, project_root=str(Path(__file__).parents[2]), capture_exception_code_variables=False, @@ -257,8 +267,8 @@ def test_does_not_normalize_unexpected_user_agent(user_agent): } -def test_legacy_capture_identify_alias_and_group_identify_request_snapshot(): - _assert_json_snapshot("legacy_event_family", _legacy_event_family_request()) +def test_capture_identify_alias_and_group_identify_request_snapshot(): + _assert_json_snapshot("event_family", _event_family_request()) def test_complete_exception_request_snapshot(): diff --git a/posthog/test/test_utils.py b/posthog/test/test_utils.py index c8d5e5a1b..ab5a759aa 100644 --- a/posthog/test/test_utils.py +++ b/posthog/test/test_utils.py @@ -4,12 +4,12 @@ import time import unittest from collections import deque -from contextlib import ExitStack +from contextlib import ExitStack, contextmanager from unittest import mock from dataclasses import dataclass from datetime import date, datetime, timedelta, timezone, tzinfo from decimal import Decimal -from typing import Optional +from typing import Iterator, Optional from uuid import UUID from parameterized import parameterized @@ -23,6 +23,21 @@ FAKE_TEST_API_KEY = "random_key" +@contextmanager +def local_timezone(tz: str) -> Iterator[None]: + original_tz = os.environ.get("TZ") + os.environ["TZ"] = tz + time.tzset() + try: + yield + finally: + if original_tz is None: + os.environ.pop("TZ", None) + else: + os.environ["TZ"] = original_tz + time.tzset() + + class FakeRedis: def __init__(self, fail=False): self.store = {} @@ -126,10 +141,7 @@ def test_timezone_utils(self): @unittest.skipUnless(hasattr(time, "tzset"), "requires time.tzset") def test_guess_timezone_preserves_recent_naive_local_instant_as_utc(self): - original_tz = os.environ.get("TZ") - try: - os.environ["TZ"] = "EST5EDT" - time.tzset() + with local_timezone("EST5EDT"): local_now = datetime(2026, 1, 15, 7, 30, 45, 123456) utc_now = datetime(2026, 1, 15, 12, 30, 45, 123456, tzinfo=timezone.utc) @@ -141,32 +153,17 @@ def test_guess_timezone_preserves_recent_naive_local_instant_as_utc(self): assert normalized == utc_now assert normalized.isoformat() == "2026-01-15T12:30:45.123456+00:00" - finally: - if original_tz is None: - os.environ.pop("TZ", None) - else: - os.environ["TZ"] = original_tz - time.tzset() @unittest.skipUnless(hasattr(time, "tzset"), "requires time.tzset") def test_normalize_timestamp_treats_future_naive_string_as_utc(self): - original_tz = os.environ.get("TZ") - try: - os.environ["TZ"] = "EST5EDT" - time.tzset() + with local_timezone("EST5EDT"): now = datetime(2026, 1, 15, 12, 30, tzinfo=timezone.utc) with mock.patch("posthog.utils.datetime", wraps=datetime) as mock_datetime: mock_datetime.now.return_value = now.replace(tzinfo=None) normalized = utils._normalize_timestamp("2030-01-01T12:00:00") - assert normalized == "2030-01-01T12:00:00+00:00" - finally: - if original_tz is None: - os.environ.pop("TZ", None) - else: - os.environ["TZ"] = original_tz - time.tzset() + assert normalized == "2030-01-01T12:00:00.000000+00:00" def test_normalize_timestamp_converts_datetime_to_utc(self): timestamp = datetime( @@ -177,12 +174,39 @@ def test_normalize_timestamp_converts_datetime_to_utc(self): utils._normalize_timestamp(timestamp) == "2026-01-15T12:30:45.123456+00:00" ) + @parameterized.expand( + [ + ( + "whole_second_keeps_zero_fraction", + datetime(2026, 1, 15, 12, 0, 0, tzinfo=timezone.utc), + "2026-01-15T12:00:00.000000+00:00", + ), + ( + "microseconds_kept", + datetime(2026, 1, 15, 12, 0, 0, 120000, tzinfo=timezone.utc), + "2026-01-15T12:00:00.120000+00:00", + ), + ( + "offset_converted_to_utc", + datetime(2026, 1, 15, 7, 30, 0, tzinfo=timezone(timedelta(hours=-5))), + "2026-01-15T12:30:00.000000+00:00", + ), + ] + ) + @unittest.skipUnless(hasattr(time, "tzset"), "requires time.tzset") + def test_rfc3339_timestamp_always_writes_the_fraction_in_utc( + self, _name: str, value: datetime, expected: str + ): + # A non-UTC local zone tells UTC conversion apart from local conversion. + with local_timezone("EST5EDT"): + assert utils._rfc3339_timestamp(value) == expected + def test_normalize_timestamp_converts_compact_offset_to_utc(self): with mock.patch("posthog.utils.datetime", wraps=datetime) as mock_datetime: normalized = utils._normalize_timestamp("2026-06-27T12:00:00+0530") mock_datetime.fromisoformat.assert_called_once_with("2026-06-27T12:00:00+05:30") - assert normalized == "2026-06-27T06:30:00+00:00" + assert normalized == "2026-06-27T06:30:00.000000+00:00" @parameterized.expand(["2026-06-27", "20260627", "not-Z-an-iso-timestamp"]) def test_normalize_timestamp_rejects_invalid_string(self, timestamp): @@ -262,6 +286,32 @@ def test_clean_fn(self): def test_remove_slash(self, input_url, expected_url): assert expected_url == utils.remove_trailing_slash(input_url) + @parameterized.expand( + [ + ("random_ones", b"\xff" * 10, "01234567-89ab-7fff-bfff-ffffffffffff"), + ("random_zeros", b"\x00" * 10, "01234567-89ab-7000-8000-000000000000"), + ( + "random_mixed", + bytes(range(0x10, 0x1A)), + "01234567-89ab-7011-9213-141516171819", + ), + ] + ) + def test_uuid7_layout(self, _name, random_bytes, expected): + # Bit 48 of the millisecond clock is set to check that it is masked off. + time_ns = ((1 << 48) + 0x0123456789AB) * 1_000_000 + 999_999 + with ( + mock.patch.object(utils.time, "time_ns", return_value=time_ns), + mock.patch.object( + utils.os, + "urandom", + side_effect=lambda n: (random_bytes + b"\xaa" * n)[:n], + ), + ): + value = utils._uuid7() + self.assertEqual(str(value), expected) + self.assertEqual(value.version, 7) + def test_clean_pydantic(self): class ModelV2(BaseModel): foo: str @@ -339,11 +389,125 @@ def clean_or_raise(value): ): assert utils._clean_dict({"ok": 1, "bad": bad_value}) == {"ok": 1} - warning.assert_called_once() - assert warning.call_args.args[0] == ( - 'Dictionary values must be serializeable to JSON "%s" value %s of type %s is unsupported.' + warning.assert_called_once_with( + 'Dictionary value for key "%s" of type %s is not JSON serializable, dropping it.', + "bad", + type(bad_value), + ) + + @parameterized.expand( + [ + ("missing", None, "missing"), + ("non_string", 123, "non-string"), + ("bytes", b"event", "non-string"), + ("empty", "", "empty"), + ("valid", "signed_up", None), + ("whitespace_is_a_name", " ", None), + ] + ) + def test_invalid_event_name_reason(self, _, event, expected): + assert utils._invalid_event_name_reason(event) == expected + + def test_drop_invalid_event_name_logs_each_reason_once(self): + logger = mock.Mock() + with mock.patch.object(utils, "_warned_reasons", set()): + dropped = [ + utils._drop_invalid_event_name(logger, msg) + for msg in ({"event": None}, {}, {"event": ""}, {"event": "ok"}) + ] + + assert dropped == [True, True, True, False] + message = ( + "Dropping an event with a %s name: event names must be non-empty strings. " + "Later events dropped for the same reason are not logged." + ) + assert logger.warning.call_args_list == [ + mock.call(message, "missing"), + mock.call(message, "empty"), + ] + + def test_before_send_logs_name_the_event_and_never_the_exception_message(self): + logger = mock.Mock() + error = ValueError("secret@example.com") + + utils._log_before_send_error(logger, "signup", error) + utils._log_before_send_bad_return(logger, "signup", ["not", "a", "dict"]) + + assert logger.method_calls == [ + mock.call.error( + "Error in before_send callback for event %s (%s), dropping the event", + "signup", + "ValueError", + ), + mock.call.debug("before_send callback traceback", exc_info=error), + mock.call.error( + "before_send must return a dict or None, not %s, dropping event %s", + "list", + "signup", + ), + ] + + def test_drop_invalid_distinct_id_logs_each_reason_once(self): + logger = mock.Mock() + with mock.patch.object(utils, "_warned_reasons", set()): + dropped = [ + utils._drop_invalid_distinct_id(logger, msg) + for msg in ( + {"distinct_id": None}, + {}, + {"distinct_id": 123}, + {"distinct_id": ["a"]}, + {"distinct_id": "user"}, + {"distinct_id": ""}, + ) + ] + + assert dropped == [True, True, True, True, False, False] + message = ( + "Dropping an event with a %s distinct_id: distinct IDs must be strings. " + "Later events dropped for the same reason are not logged." + ) + assert logger.warning.call_args_list == [ + mock.call(message, "missing"), + mock.call(message, "non-string"), + ] + + def test_warn_once_logs_each_reason_once(self): + logger = mock.Mock() + with mock.patch.object(utils, "_warned_reasons", set()): + utils._warn_once(logger, "a", "first %s", 1) + utils._warn_once(logger, "a", "again %s", 2) + utils._warn_once(logger, "b", "second") + + assert logger.warning.call_args_list == [ + mock.call("first %s", 1), + mock.call("second"), + ] + + @parameterized.expand( + [ + ("personal", "phx_abc", True), + ("project", "phc_abc", False), + ("prefix_elsewhere", "abc_phx_", False), + ("empty", "", False), + ] + ) + def test_is_personal_api_key(self, _, api_key, expected): + assert utils._is_personal_api_key(api_key) is expected + + def test_clean_drops_only_keys_json_cannot_write(self): + cleaned = utils.clean( + { + ("t",): "tuple", + "s": 1, + 2: "int", + 1.5: "float", + True: "bool", + None: "none", + } ) - assert warning.call_args.args[1:] == ("bad", bad_value, type(bad_value)) + assert cleaned == {"s": 1, 2: "int", 1.5: "float", True: "bool", None: "none"} + json.dumps(cleaned) def test_coerce_unicode(self): assert utils._coerce_unicode("already unicode") == "already unicode" diff --git a/posthog/test/tracing/test_client_traces.py b/posthog/test/tracing/test_client_traces.py index ab9d0ee0e..f3b2b48c9 100644 --- a/posthog/test/tracing/test_client_traces.py +++ b/posthog/test/tracing/test_client_traces.py @@ -15,6 +15,7 @@ from posthog.tracing._transport import OK from posthog.tracing._span import NOOP_SPAN, RecordingSpan, Span from posthog.version import VERSION +from posthog.test.capture_helpers import patch_capture_send, sent_batch FAKE_API_KEY = "phc_test_key" @@ -671,10 +672,10 @@ def test_the_span_exit_drain_leaves_sync_mode_events_alone(self): client.start_span("x").end() with mock.patch("posthog.client._atexit_deadline", None): client._atexit_spans() - with mock.patch("posthog.client.batch_post") as batch_post: + with patch_capture_send("client") as batch_post: client.capture("after-exit", distinct_id="d") batch_post.assert_called_once() - assert batch_post.call_args[1]["batch"][0]["event"] == "after-exit" + assert sent_batch(batch_post)[0]["event"] == "after-exit" client.shutdown() @pytest.mark.parametrize("traces", [{}, None]) diff --git a/posthog/tracing/_export.py b/posthog/tracing/_export.py index a68c5716e..156276e25 100644 --- a/posthog/tracing/_export.py +++ b/posthog/tracing/_export.py @@ -12,7 +12,7 @@ import time from typing import Any, Callable, List, Optional, Tuple -from ..capture_v1 import _MAX_BACKOFF_SECONDS +from ..capture_send import _MAX_BACKOFF_SECONDS from ._config import ResolvedTracesConfig from ._drops import DropLog from ._limits import truncate_attributes diff --git a/posthog/tracing/span.py b/posthog/tracing/span.py index 8bd401ecf..ce9db69c3 100644 --- a/posthog/tracing/span.py +++ b/posthog/tracing/span.py @@ -89,6 +89,12 @@ def record_exception(self, exception: BaseException) -> "Span": ``with span:`` a raised ``Exception`` is recorded automatically, so this is for exceptions that are caught and handled. + The stack trace contains file paths from your server. Remove + ``exception.stacktrace`` in ``before_span_send`` to keep them in your + process. The ``exception`` event uses one of the span's event slots. A + span whose event slots are full keeps its ``error`` status and the + exception message, but loses the exception type and stack trace. + Examples: ```python try: diff --git a/posthog/utils.py b/posthog/utils.py index cfa508565..a734fa2d3 100644 --- a/posthog/utils.py +++ b/posthog/utils.py @@ -1,6 +1,7 @@ import json import logging import numbers +import os import re import threading import time @@ -49,6 +50,30 @@ def guess_timezone(dt: datetime) -> datetime: return dt.astimezone(timezone.utc) +def _uuid7() -> UUID: + """Return a time-ordered version 7 UUID (RFC 9562). + + Capture generates v7 server-side when a client omits the uuid, so + SDK-generated event uuids sort the same way. + """ + unix_ms = time.time_ns() // 1_000_000 + # Python 3.10 requires the byte order; from 3.11 "big" is the default. + random_bits = int.from_bytes(os.urandom(10), "big") # pragma: no mutate + value = ((unix_ms & ((1 << 48) - 1)) << 80) | random_bits + value = (value & ~(0xF << 76)) | (0x7 << 76) + value = (value & ~(0x3 << 62)) | (0x2 << 62) + return UUID(int=value) + + +def _rfc3339_timestamp(dt: datetime) -> str: + """Format an aware datetime as a UTC RFC 3339 string for the capture wire. + + The fraction is always six digits, even when zero, because plain + ``isoformat()`` drops it for whole seconds. + """ + return dt.astimezone(timezone.utc).isoformat(timespec="microseconds") + + def _normalize_timestamp(timestamp: Union[datetime, str]) -> str: """Normalize a datetime or parseable ISO datetime string to UTC.""" parsed_timestamp: datetime @@ -71,7 +96,7 @@ def _normalize_timestamp(timestamp: Union[datetime, str]) -> str: ) from None else: parsed_timestamp = timestamp - return guess_timezone(parsed_timestamp).isoformat() + return _rfc3339_timestamp(guess_timezone(parsed_timestamp)) def remove_trailing_slash(host: str) -> str: @@ -118,16 +143,110 @@ def _clean_list(list_): return [clean(item) for item in list_] +_warned_reasons: set[str] = set() +_warned_reasons_lock = threading.Lock() + + +def _warn_once(logger: logging.Logger, reason: str, message: str, *args: Any) -> None: + """Log `message` the first time `reason` occurs in this process, then stay silent. + + For drops caused by caller input, which can repeat at event rate. + """ + with _warned_reasons_lock: + if reason in _warned_reasons: + return + _warned_reasons.add(reason) + logger.warning(message, *args) + + +def _is_personal_api_key(api_key: str) -> bool: + """A personal API key (phx_...) is never a project API key; capture rejects it.""" + return api_key.startswith("phx_") + + +def _invalid_event_name_reason(event: Any) -> Optional[str]: + """Why capture would reject `event` as an event name, or None if it is valid.""" + if event is None: + return "missing" + if not isinstance(event, str): + return "non-string" + if not event: + return "empty" + return None + + +def _drop_invalid_event_name(logger: logging.Logger, msg: dict) -> bool: + """True when `msg` has an event name capture would reject; logs once per reason.""" + reason = _invalid_event_name_reason(msg.get("event")) + if reason is None: + return False + _warn_once( + logger, + f"event_name_{reason}", # pragma: no mutate + "Dropping an event with a %s name: event names must be non-empty strings. " + "Later events dropped for the same reason are not logged.", + reason, + ) + return True + + +def _log_before_send_error( + logger: logging.Logger, event_name: Any, error: Exception +) -> None: + """Log a raising before_send hook without its message, which can hold event data.""" + logger.error( + "Error in before_send callback for event %s (%s), dropping the event", + event_name, + type(error).__name__, + ) + logger.debug("before_send callback traceback", exc_info=error) + + +def _log_before_send_bad_return( + logger: logging.Logger, event_name: Any, result: Any +) -> None: + logger.error( + "before_send must return a dict or None, not %s, dropping event %s", + type(result).__name__, + event_name, + ) + + +def _drop_invalid_distinct_id(logger: logging.Logger, msg: dict) -> bool: + """True when `msg` has no string distinct_id; logs once per reason. + + Runs after before_send, which may set any value; the SDK never converts it there. + """ + distinct_id = msg.get("distinct_id") + if isinstance(distinct_id, str): + return False + reason = "missing" if distinct_id is None else "non-string" + _warn_once( + logger, + f"distinct_id_{reason}", # pragma: no mutate + "Dropping an event with a %s distinct_id: distinct IDs must be strings. " + "Later events dropped for the same reason are not logged.", + reason, + ) + return True + + +# The key types json.dumps can write; it converts the non-string ones to strings. +_JSON_KEY_TYPES = (str, int, float, bool, type(None)) + + def _clean_dict(dict_): data = {} for k, v in dict_.items(): + # Drop only a key json cannot write, so one bad key never costs the event. + if not isinstance(k, _JSON_KEY_TYPES): + continue try: data[k] = clean(v) except TypeError: log.warning( - 'Dictionary values must be serializeable to JSON "%s" value %s of type %s is unsupported.', + 'Dictionary value for key "%s" of type %s is not JSON serializable, dropping it.', k, - v, type(v), ) return data diff --git a/pyproject.toml b/pyproject.toml index 732c394ba..7eeaa0c9e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -24,7 +24,6 @@ classifiers = [ ] dependencies = [ "requests>=2.7,<3.0", - "backoff>=1.10.0", "distro>=1.5.0", "typing-extensions>=4.2.0", ] diff --git a/references/posthog-python-7.md b/references/posthog-python-7.md index 736d03a5a..a9ed00bd7 100644 --- a/references/posthog-python-7.md +++ b/references/posthog-python-7.md @@ -89,7 +89,7 @@ To send your first event, install the package, create a client, capture an event ### Install ```bash -pip install posthog +pip install "posthog>=7,<8" ``` ### Initialize diff --git a/references/posthog-python-8.md b/references/posthog-python-8.md index 7f7416cfa..a7d441aa7 100644 --- a/references/posthog-python-8.md +++ b/references/posthog-python-8.md @@ -662,7 +662,7 @@ Name | Type | Description | Default Type | Description ---- | ----------- -`Optional[FeatureFlagResult]` | Optional[FeatureFlagResult]: The feature flag result or None if disabled/not found. +`Optional[FeatureFlagResult]` | Optional[FeatureFlagResult]: The evaluated result, including a healthy disabled flag, or None when no result is available (for example, a missing flag or a server-marked failure without a successful fallback). ## Get feature flags @@ -1385,11 +1385,8 @@ Name | Type | Description `capture_exceptions` | `Optional[bool]` | `capture_tracing_headers` | | `client` | | -`extra_properties` | | `extra_tags` | | Compatibility alias for `extra_properties`. `get_response` | | -`properties_map` | | -`request_filter` | | `sync_capable` | | `tag_map` | | Compatibility alias for `properties_map`. `trust_tracing_headers` | `bool` | Deprecated alias for `capture_tracing_headers`. @@ -1460,12 +1457,6 @@ capture_tracing_headers = _resolve_capture_tracing_headers(capture_tracing_heade client = cast('Optional[Client]', settings.POSTHOG_MW_CLIENT) ``` -#### `posthog.integrations.django.PosthogContextMiddleware.extra_properties` - -```python -extra_properties = cast('Callable[[HttpRequest], Dict[str, Any]]', extra_properties) if callable(extra_properties) else None -``` - #### `posthog.integrations.django.PosthogContextMiddleware.extra_tags` ```python @@ -1521,18 +1512,6 @@ the middleware stack, so the context manager in __call__/__acall__ never sees th Note: Django's process_exception is always synchronous, even for async views. -#### `posthog.integrations.django.PosthogContextMiddleware.properties_map` - -```python -properties_map = cast('Callable[[Dict[str, Any]], Dict[str, Any]]', properties_map) if callable(properties_map) else None -``` - -#### `posthog.integrations.django.PosthogContextMiddleware.request_filter` - -```python -request_filter = cast('Optional[Callable[[HttpRequest], bool]]', settings.POSTHOG_MW_REQUEST_FILTER) -``` - #### `posthog.integrations.django.PosthogContextMiddleware.sync_capable` ```python @@ -3205,7 +3184,7 @@ Name | Description `get_flag` | Return the flag value. Fires `$feature_flag_called` on first access. `get_flag_payload` | Return the payload associated with a flag. `is_enabled` | Return whether the flag is enabled. Fires `$feature_flag_called` on the first access per (distinct_id, flag, value) tuple, deduped via the SDK's cache. -`only` | Return a filtered copy containing only flags with the given keys. Keys that are not present in the evaluation are dropped and logged as a warning. +`only` | Return a filtered copy containing only flags with the given keys. Keys that are not present in the evaluation are dropped and logged as a warning. Selected failures retain private diagnostics but remain absent from values, keys and enrichment; their existing missing-value warning is unchanged. `only_accessed` | Return a filtered copy containing only flags accessed via `is_enabled` or `get_flag` before this call. **Attributes:** @@ -3227,7 +3206,8 @@ Return the flag value. Fires `$feature_flag_called` on first access. Returns the variant string for multivariate flags, `True` for enabled flags without a variant, `False` for disabled flags, and `None` for flags that -were not returned by the evaluation. +were not returned or whose remote record was marked failed by the server. +An unreadable remote record retains its disabled (`False`) result. Pass `send_feature_flag_events=False` to skip the event for this read, as with `is_enabled`. @@ -3256,7 +3236,7 @@ first access per (distinct_id, flag, value) tuple, deduped via the SDK's cache. Name | Type | Description | Default ---- | ---- | ----------- | ------- `key` | `str` | The feature flag key. | *required* -`default_value` | `bool` | Returned when the flag has no value in this evaluation — the key was not part of the evaluated set, or the evaluation itself came back empty (failed `/flags` request, quota limit, or no resolvable `distinct_id`). Defaults to `False`. | `False` +`default_value` | `bool` | Returned when the flag has no value in this evaluation — the key was not part of the evaluated set, the server marked its record failed, or the evaluation itself came back empty (failed `/flags` request, quota limit, or no resolvable `distinct_id`). Defaults to `False`. | `False` `send_feature_flag_events` | `bool` | Whether this read sends `$feature_flag_called`. When `False`, no event is sent and the dedupe cache is left alone, but the key still counts as accessed for `only_accessed`. | `True` A flag that has a value always wins over `default_value`, including a @@ -3278,6 +3258,8 @@ only(keys: List[str]) -> FeatureFlagEvaluations Return a filtered copy containing only flags with the given keys. Keys that are not present in the evaluation are dropped and logged as a warning. +Selected failures retain private diagnostics but remain absent from values, +keys and enrichment; their existing missing-value warning is unchanged. #### `posthog.feature_flag_evaluations.FeatureFlagEvaluations.only_accessed` @@ -3290,6 +3272,7 @@ or `get_flag` before this call. Order-dependent: if nothing has been accessed yet, the returned snapshot is empty. The method honors its name — pre-access if you want a populated result. +Accessed failures retain private diagnostics, not values or enrichment. #### `posthog.feature_flag_evaluations.FeatureFlagEvaluations.unresolved_flags` @@ -3303,8 +3286,9 @@ left it without a value. A flag is listed when it has a loaded local definition, was in the requested scope, was inconclusive locally, and no remote value filled the gap. Listed flags are not part of `keys`, and reading one reports the -`local_evaluation_inconclusive` error instead of `flag_missing`. Reading -this mapping does not count as an access and does not fire any event. +`local_evaluation_inconclusive` error instead of `flag_missing`. +A server-marked failed fallback additionally reports `evaluation_failed`. +Reading this mapping does not count as an access and does not fire any event. Snapshots returned by `only` and `only_accessed`, and by `AsyncClient.evaluate_flags()`, which evaluates only remotely, carry no entries. @@ -3354,13 +3338,13 @@ Create a FeatureFlagResult from a FeatureFlag object. Name | Type | Description | Default ---- | ---- | ----------- | ------- `details` | `Union[FeatureFlag, None]` | The FeatureFlag object to convert. | *required* -`override_match_value` | `Optional[FlagValue]` | If provided, this value will be used to populate the enabled and variant fields instead of the values from the FeatureFlag. | `None` +`override_match_value` | `Optional[FlagValue]` | If provided, this value will be used to populate the enabled and variant fields instead of the values from the FeatureFlag. A server-marked failure returns None even when this override is provided. | `None` **Returns:** Type | Description ---- | ----------- -`FeatureFlagResult \| None` | FeatureFlagResult | None: A new FeatureFlagResult instance, or None if details is None. +`FeatureFlagResult \| None` | FeatureFlagResult | None: A new result, or None when details is absent or the server marked the record failed. Unreadable records are not treated as server-marked failures. #### `posthog.types.FeatureFlagResult.from_value_and_payload` @@ -4086,7 +4070,7 @@ Type | Description Type | Description ---- | ----------- -`EmailError` | PostHog did not queue the email, or the client could not tell whether it did. +`EmailError` | PostHog did not queue the email, or the client could not tell whether it did. With attachments, `code` is `too_many_attachments`, `message_too_large` or `invalid_attachment` before any request, `attachment_upload_failed` when the storage refused an upload, and `network_error` with `field` naming the attachment when the storage didn't answer. `(TypeError, ValueError)` | An argument has the wrong type or format. **Examples:** @@ -4305,6 +4289,10 @@ your app first. An optional field passed as `None` counts as left out. +A PostHog version that doesn't take a field yet, such as `cc`, refuses +the send with an error that names the field in `EmailError.field`. It +never drops the field and sends the rest. + **Parameters:** Name | Type | Description | Default @@ -4316,7 +4304,12 @@ Name | Type | Description | Default `text` | | The plain-text body. Without it, PostHog derives it from `html`. HTML with no text in it, such as a single image, goes out without a plain-text part. | `from_` | | A verified sender, such as `"Acme "`. | `reply_to` | | One address or a list of addresses. An empty list sends no reply-to. | -`capture_engagement` | | Capture the email's opens and clicks as events of the recipient. Defaults to `True`. A project whose admin turned engagement capture off captures nothing, whatever the send asks. A template made in PostHog follows the project's setting, so the template form doesn't take it. | +`cc` | | One address or a list of addresses that get a visible copy, at most 10. | +`bcc` | | One address or a list of addresses that get a hidden copy, at most 10. | +`attachments` | | Files sent with the email: at most 10 files and 40 MB per message after Base64 encoding, about 29 MB of files. The client checks both before any request. It uploads each file that PostHog doesn't hold yet, then sends the email. A file the client can't send raises `EmailError` with `code` `invalid_attachment`. | +`capture_engagement` | | Deprecated, use `tracking={"engagement": False}`. It keeps working, but PostHog refuses a send that sets both `capture_engagement` and `tracking`. Captures the email's engagement events as events of the recipient. Defaults to `True`. A project whose admin turned engagement capture off captures nothing, whatever the send asks. A template made in PostHog follows the project's setting, so the template form doesn't take it. | +`sensitive` | | Marks the email as sensitive, such as one that carries login links, reset tokens or codes. A sensitive email keeps its links as they are unless `tracking` turns clicks on, leaves its subject off engagement events, and keeps its content out of PostHog's logs. Without it, a send whose `template_key` matches a template saved in PostHog follows that template's setting, and any other send is sensitive. The template form doesn't take it. | +`tracking` | | What PostHog tracks for this email. Without it, PostHog counts opens with its open pixel, captures engagement events, and counts clicks only when the email isn't sensitive. `True` turns on opens, clicks and engagement events. `False` turns off all tracking, including kinds PostHog adds later: PostHog can't count the email's opens or clicks, and captures no engagement events. An `EmailTracking` dict turns each kind on or off, and a key you leave out keeps its default. Turn clicks on for a sensitive email only when its links are safe to send through PostHog's click tracking. The template form doesn't take it. | `distinct_id` | | The recipient's distinct ID in your product. | `idempotency_key` | | 1 to 255 visible ASCII characters. Template sends and code sends share one set of keys: a key already used for another email, or for a `template_id` send, raises `idempotency_key_reused`. A retry with the same key returns the first send's result, also when its workflow was paused since. | `max_retries` | | Overrides the client's maximum number of retries for this send. `0` turns retries off. | @@ -4325,17 +4318,34 @@ Name | Type | Description | Default Name | Type | Description ---- | ---- | ----------- +`attachments` | `NotRequired[Optional[Sequence[EmailAttachment]]]` | +`bcc` | `NotRequired[Optional[Union[str, Sequence[str]]]]` | `capture_engagement` | `NotRequired[Optional[bool]]` | +`cc` | `NotRequired[Optional[Union[str, Sequence[str]]]]` | `distinct_id` | `NotRequired[Optional[str]]` | `from_` | `NotRequired[Optional[str]]` | `html` | `NotRequired[Optional[str]]` | `idempotency_key` | `NotRequired[Optional[str]]` | `max_retries` | `NotRequired[Optional[int]]` | `reply_to` | `NotRequired[Optional[Union[str, Sequence[str]]]]` | +`sensitive` | `NotRequired[Optional[bool]]` | `subject` | `str` | `template_key` | `str` | `text` | `NotRequired[Optional[str]]` | `to` | `str` | +`tracking` | `NotRequired[Optional[Union[bool, EmailTracking]]]` | + +#### `posthog.emails.CodeEmailArgs.attachments` + +```python +attachments: NotRequired[Optional[Sequence[EmailAttachment]]] +``` + +#### `posthog.emails.CodeEmailArgs.bcc` + +```python +bcc: NotRequired[Optional[Union[str, Sequence[str]]]] +``` #### `posthog.emails.CodeEmailArgs.capture_engagement` @@ -4343,6 +4353,12 @@ Name | Type | Description capture_engagement: NotRequired[Optional[bool]] ``` +#### `posthog.emails.CodeEmailArgs.cc` + +```python +cc: NotRequired[Optional[Union[str, Sequence[str]]]] +``` + #### `posthog.emails.CodeEmailArgs.distinct_id` ```python @@ -4379,6 +4395,12 @@ max_retries: NotRequired[Optional[int]] reply_to: NotRequired[Optional[Union[str, Sequence[str]]]] ``` +#### `posthog.emails.CodeEmailArgs.sensitive` + +```python +sensitive: NotRequired[Optional[bool]] +``` + #### `posthog.emails.CodeEmailArgs.subject` ```python @@ -4402,3 +4424,9 @@ text: NotRequired[Optional[str]] ```python to: str ``` + +#### `posthog.emails.CodeEmailArgs.tracking` + +```python +tracking: NotRequired[Optional[Union[bool, EmailTracking]]] +``` diff --git a/references/posthog-python-reference.md b/references/posthog-python-reference.md index 3d3e31800..cae9b2aa5 100644 --- a/references/posthog-python-reference.md +++ b/references/posthog-python-reference.md @@ -89,7 +89,7 @@ To send your first event, install the package, create a client, capture an event ### Install ```bash -pip install posthog +pip install "posthog>=7,<8" ``` ### Initialize diff --git a/references/public_api_snapshot.txt b/references/public_api_snapshot.txt index 4b51f85aa..c9e0b430e 100644 --- a/references/public_api_snapshot.txt +++ b/references/public_api_snapshot.txt @@ -7,7 +7,7 @@ alias posthog.AsyncClient -> posthog.async_client.AsyncClient alias posthog.AsyncPosthog -> posthog.async_client.AsyncPosthog alias posthog.BeforeSendCallback -> posthog.types.BeforeSendCallback alias posthog.CaptureCompression -> posthog.capture_compression.CaptureCompression -alias posthog.CaptureMode -> posthog.capture_mode.CaptureMode +alias posthog.CaptureError -> posthog.capture_send.CaptureError alias posthog.Client -> posthog.client.Client alias posthog.DEFAULT_CODE_VARIABLES_DETECT_SECRETS -> posthog.exception_utils.DEFAULT_CODE_VARIABLES_DETECT_SECRETS alias posthog.DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS -> posthog.exception_utils.DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS @@ -52,7 +52,6 @@ alias posthog.ai.anthropic.anthropic.handle_anthropic_content_block_start -> pos alias posthog.ai.anthropic.anthropic.handle_anthropic_text_delta -> posthog.ai.anthropic.anthropic_converter.handle_anthropic_text_delta alias posthog.ai.anthropic.anthropic.handle_anthropic_tool_delta -> posthog.ai.anthropic.anthropic_converter.handle_anthropic_tool_delta alias posthog.ai.anthropic.anthropic.merge_usage_stats -> posthog.ai.utils.merge_usage_stats -alias posthog.ai.anthropic.anthropic.setup -> posthog.setup alias posthog.ai.anthropic.anthropic_async.AsyncStreamWrapper -> posthog.ai.stream.AsyncStreamWrapper alias posthog.ai.anthropic.anthropic_async.PostHogClient -> posthog.client.Client alias posthog.ai.anthropic.anthropic_async.StreamingContentBlock -> posthog.ai.types.StreamingContentBlock @@ -65,7 +64,6 @@ alias posthog.ai.anthropic.anthropic_async.handle_anthropic_content_block_start alias posthog.ai.anthropic.anthropic_async.handle_anthropic_text_delta -> posthog.ai.anthropic.anthropic_converter.handle_anthropic_text_delta alias posthog.ai.anthropic.anthropic_async.handle_anthropic_tool_delta -> posthog.ai.anthropic.anthropic_converter.handle_anthropic_tool_delta alias posthog.ai.anthropic.anthropic_async.merge_usage_stats -> posthog.ai.utils.merge_usage_stats -alias posthog.ai.anthropic.anthropic_async.setup -> posthog.setup alias posthog.ai.anthropic.anthropic_converter.FormattedContentItem -> posthog.ai.types.FormattedContentItem alias posthog.ai.anthropic.anthropic_converter.FormattedFunctionCall -> posthog.ai.types.FormattedFunctionCall alias posthog.ai.anthropic.anthropic_converter.FormattedMessage -> posthog.ai.types.FormattedMessage @@ -78,7 +76,6 @@ alias posthog.ai.anthropic.anthropic_converter.to_plain -> posthog.ai.media.to_p alias posthog.ai.anthropic.anthropic_providers.AsyncWrappedMessages -> posthog.ai.anthropic.anthropic_async.AsyncWrappedMessages alias posthog.ai.anthropic.anthropic_providers.PostHogClient -> posthog.client.Client alias posthog.ai.anthropic.anthropic_providers.WrappedMessages -> posthog.ai.anthropic.anthropic.WrappedMessages -alias posthog.ai.anthropic.anthropic_providers.setup -> posthog.setup alias posthog.ai.anthropic.extract_anthropic_tools -> posthog.ai.anthropic.anthropic_converter.extract_anthropic_tools alias posthog.ai.anthropic.format_anthropic_input -> posthog.ai.anthropic.anthropic_converter.format_anthropic_input alias posthog.ai.anthropic.format_anthropic_response -> posthog.ai.anthropic.anthropic_converter.format_anthropic_response @@ -95,7 +92,6 @@ alias posthog.ai.claude_agent_sdk.processor.Client -> posthog.client.Client alias posthog.ai.claude_agent_sdk.processor.finalize_ai_content -> posthog.ai.utils.finalize_ai_content alias posthog.ai.claude_agent_sdk.processor.format_assistant_blocks -> posthog.ai.claude_agent_sdk.formatting.format_assistant_blocks alias posthog.ai.claude_agent_sdk.processor.format_tool_result_content -> posthog.ai.claude_agent_sdk.formatting.format_tool_result_content -alias posthog.ai.claude_agent_sdk.processor.setup -> posthog.setup alias posthog.ai.gemini.AsyncClient -> posthog.ai.gemini.gemini_async.AsyncClient alias posthog.ai.gemini.Client -> posthog.ai.gemini.gemini.Client alias posthog.ai.gemini.extract_gemini_tools -> posthog.ai.gemini.gemini_converter.extract_gemini_tools @@ -146,7 +142,6 @@ alias posthog.ai.langchain.CallbackHandler -> posthog.ai.langchain.callbacks.Cal alias posthog.ai.langchain.callbacks.Client -> posthog.client.Client alias posthog.ai.langchain.callbacks.finalize_ai_content -> posthog.ai.utils.finalize_ai_content alias posthog.ai.langchain.callbacks.get_model_params -> posthog.ai.utils.get_model_params -alias posthog.ai.langchain.callbacks.setup -> posthog.setup alias posthog.ai.langchain.callbacks.warn_if_posthog_ai_gateway -> posthog.ai.gateway.warn_if_posthog_ai_gateway alias posthog.ai.langchain.callbacks.with_privacy_mode -> posthog.ai.utils.with_privacy_mode alias posthog.ai.openai.AsyncAzureOpenAI -> posthog.ai.openai.openai_providers.AsyncAzureOpenAI @@ -168,7 +163,6 @@ alias posthog.ai.openai.openai.extract_openai_usage_from_chunk -> posthog.ai.ope alias posthog.ai.openai.openai.finalize_ai_content -> posthog.ai.utils.finalize_ai_content alias posthog.ai.openai.openai.merge_provider_override -> posthog.ai.openai.wrapper_utils.merge_provider_override alias posthog.ai.openai.openai.merge_usage_stats -> posthog.ai.utils.merge_usage_stats -alias posthog.ai.openai.openai.setup -> posthog.setup alias posthog.ai.openai.openai.with_privacy_mode -> posthog.ai.utils.with_privacy_mode alias posthog.ai.openai.openai_async.AsyncStreamWrapper -> posthog.ai.stream.AsyncStreamWrapper alias posthog.ai.openai.openai_async.PostHogClient -> posthog.client.Client @@ -185,7 +179,6 @@ alias posthog.ai.openai.openai_async.format_openai_streaming_output -> posthog.a alias posthog.ai.openai.openai_async.get_model_params -> posthog.ai.utils.get_model_params alias posthog.ai.openai.openai_async.merge_provider_override -> posthog.ai.openai.wrapper_utils.merge_provider_override alias posthog.ai.openai.openai_async.merge_usage_stats -> posthog.ai.utils.merge_usage_stats -alias posthog.ai.openai.openai_async.setup -> posthog.setup alias posthog.ai.openai.openai_async.with_privacy_mode -> posthog.ai.utils.with_privacy_mode alias posthog.ai.openai.openai_converter.FormattedContentItem -> posthog.ai.types.FormattedContentItem alias posthog.ai.openai.openai_converter.FormattedFunctionCall -> posthog.ai.types.FormattedFunctionCall @@ -204,11 +197,9 @@ alias posthog.ai.openai.openai_providers.WrappedBeta -> posthog.ai.openai.openai alias posthog.ai.openai.openai_providers.WrappedChat -> posthog.ai.openai.openai.WrappedChat alias posthog.ai.openai.openai_providers.WrappedEmbeddings -> posthog.ai.openai.openai.WrappedEmbeddings alias posthog.ai.openai.openai_providers.WrappedResponses -> posthog.ai.openai.openai.WrappedResponses -alias posthog.ai.openai.openai_providers.setup -> posthog.setup alias posthog.ai.openai_agents.PostHogTracingProcessor -> posthog.ai.openai_agents.processor.PostHogTracingProcessor alias posthog.ai.openai_agents.processor.Client -> posthog.client.Client alias posthog.ai.openai_agents.processor.finalize_ai_content -> posthog.ai.utils.finalize_ai_content -alias posthog.ai.openai_agents.processor.setup -> posthog.setup alias posthog.ai.otel.PostHogSpanProcessor -> posthog.ai.otel.processor.PostHogSpanProcessor alias posthog.ai.otel.PostHogTraceExporter -> posthog.ai.otel.exporter.PostHogTraceExporter alias posthog.ai.otel.exporter.Client -> posthog.client.Client @@ -233,21 +224,19 @@ alias posthog.ai.utils.identify_context -> posthog.identify_context alias posthog.ai.utils.new_context -> posthog.new_context alias posthog.ai.utils.redact_media -> posthog.ai.sanitization.redact_media alias posthog.ai.utils.sanitize_messages -> posthog.ai.sanitization.sanitize_messages +alias posthog.ai.utils.setup -> posthog.setup alias posthog.ai.utils.tag -> posthog.tag alias posthog.ai.utils.warn_if_posthog_ai_gateway -> posthog.ai.gateway.warn_if_posthog_ai_gateway alias posthog.args.FeatureFlagEvaluations -> posthog.feature_flag_evaluations.FeatureFlagEvaluations alias posthog.args.SendFeatureFlagsOptions -> posthog.types.SendFeatureFlagsOptions -alias posthog.client.AI_EVENTS_ENDPOINT -> posthog.request.AI_EVENTS_ENDPOINT alias posthog.client.AI_MAX_MSG_SIZE -> posthog.consumer.AI_MAX_MSG_SIZE alias posthog.client.APIError -> posthog.request.APIError alias posthog.client.CaptureCompression -> posthog.capture_compression.CaptureCompression -alias posthog.client.CaptureMode -> posthog.capture_mode.CaptureMode alias posthog.client.Consumer -> posthog.consumer.Consumer alias posthog.client.DEFAULT_CODE_VARIABLES_DETECT_SECRETS -> posthog.exception_utils.DEFAULT_CODE_VARIABLES_DETECT_SECRETS alias posthog.client.DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS -> posthog.exception_utils.DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS alias posthog.client.DEFAULT_CODE_VARIABLES_MASK_PATTERNS -> posthog.exception_utils.DEFAULT_CODE_VARIABLES_MASK_PATTERNS alias posthog.client.DEFAULT_CODE_VARIABLES_MASK_URL_CREDENTIALS -> posthog.exception_utils.DEFAULT_CODE_VARIABLES_MASK_URL_CREDENTIALS -alias posthog.client.EVENTS_ENDPOINT -> posthog.request.EVENTS_ENDPOINT alias posthog.client.Emails -> posthog.emails.Emails alias posthog.client.ExceptionArg -> posthog.args.ExceptionArg alias posthog.client.ExceptionCapture -> posthog.exception_capture.ExceptionCapture @@ -280,7 +269,6 @@ alias posthog.client.SizeLimitedDict -> posthog.utils.SizeLimitedDict alias posthog.client.Span -> posthog.tracing.span.Span alias posthog.client.UnresolvedFlagReason -> posthog.types.UnresolvedFlagReason alias posthog.client.VERSION -> posthog.version.VERSION -alias posthog.client.batch_post -> posthog.request.batch_post alias posthog.client.clean -> posthog.utils.clean alias posthog.client.determine_server_host -> posthog.request.determine_server_host alias posthog.client.exc_info_from_error -> posthog.exception_utils.exc_info_from_error @@ -311,12 +299,8 @@ alias posthog.client.to_flags_and_payloads -> posthog.types.to_flags_and_payload alias posthog.client.to_payloads -> posthog.types.to_payloads alias posthog.client.to_values -> posthog.types.to_values alias posthog.client.try_attach_code_variables_to_frames -> posthog.exception_utils.try_attach_code_variables_to_frames -alias posthog.consumer.APIError -> posthog.request.APIError alias posthog.consumer.CaptureCompression -> posthog.capture_compression.CaptureCompression -alias posthog.consumer.CaptureMode -> posthog.capture_mode.CaptureMode alias posthog.consumer.DatetimeSerializer -> posthog.request.DatetimeSerializer -alias posthog.consumer.EVENTS_ENDPOINT -> posthog.request.EVENTS_ENDPOINT -alias posthog.consumer.batch_post -> posthog.request.batch_post alias posthog.contexts.Client -> posthog.client.Client alias posthog.disable_connection_reuse -> posthog.request.disable_connection_reuse alias posthog.enable_keep_alive -> posthog.request.enable_keep_alive @@ -331,6 +315,7 @@ alias posthog.feature_flags.UnresolvedFlagReason -> posthog.types.UnresolvedFlag alias posthog.feature_flags.convert_to_datetime_aware -> posthog.utils.convert_to_datetime_aware alias posthog.feature_flags.is_valid_regex -> posthog.utils.is_valid_regex alias posthog.feature_flags.utils -> posthog.utils +alias posthog.inner_get_context_options -> posthog.contexts.get_context_options alias posthog.inner_get_tags -> posthog.contexts.get_tags alias posthog.inner_identify_context -> posthog.contexts.identify_context alias posthog.inner_new_context -> posthog.contexts.new_context @@ -341,6 +326,7 @@ alias posthog.inner_set_code_variables_ignore_patterns_context -> posthog.contex alias posthog.inner_set_code_variables_mask_patterns_context -> posthog.contexts.set_code_variables_mask_patterns_context alias posthog.inner_set_code_variables_mask_url_credentials_context -> posthog.contexts.set_code_variables_mask_url_credentials_context alias posthog.inner_set_context_device_id -> posthog.contexts.set_context_device_id +alias posthog.inner_set_context_option -> posthog.contexts.set_context_option alias posthog.inner_set_context_session -> posthog.contexts.set_context_session alias posthog.inner_tag -> posthog.contexts.tag alias posthog.integrations.asgi.Client -> posthog.client.Client @@ -602,12 +588,12 @@ attribute posthog.ai.evaluations.UploadReceipt.items: tuple[ItemReceipt, ...] attribute posthog.ai.evaluations.UploadReceipt.results: tuple[ResultReceipt, ...] attribute posthog.ai.gateway.POSTHOG_AI_GATEWAY_HOSTS = ['gateway.posthog.com', 'gateway.us.posthog.com', 'gateway.eu.posthog.com', 'ai-gateway.us.posthog.com', 'ai-gateway.eu.posthog.com'] attribute posthog.ai.gateway.log = logging.getLogger('posthog') -attribute posthog.ai.gemini.gemini.Client.aio = _GeminiAioNamespace(models=(AsyncModels(provider_client=(self._provider_client), posthog_client=(self._ph_client), posthog_distinct_id=posthog_distinct_id, posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, **kwargs)), files=(self._provider_client.aio.files)) +attribute posthog.ai.gemini.gemini.Client.aio = _GeminiAioNamespace(models=(AsyncModels(provider_client=(self._provider_client), posthog_client=(self._ph_client), posthog_distinct_id=posthog_distinct_id, posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, posthog_options=posthog_options, **kwargs)), files=(self._provider_client.aio.files)) attribute posthog.ai.gemini.gemini.Client.files = self._provider_client.files -attribute posthog.ai.gemini.gemini.Client.models = Models(provider_client=(self._provider_client), posthog_client=(self._ph_client), posthog_distinct_id=posthog_distinct_id, posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, **kwargs) +attribute posthog.ai.gemini.gemini.Client.models = Models(provider_client=(self._provider_client), posthog_client=(self._ph_client), posthog_distinct_id=posthog_distinct_id, posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, posthog_options=posthog_options, **kwargs) attribute posthog.ai.gemini.gemini_async.AsyncClient.aio = _GeminiAioNamespace(models=(self.models), files=(self.files)) attribute posthog.ai.gemini.gemini_async.AsyncClient.files = self._provider_client.aio.files -attribute posthog.ai.gemini.gemini_async.AsyncClient.models = AsyncModels(provider_client=(self._provider_client), posthog_client=(self._ph_client), posthog_distinct_id=posthog_distinct_id, posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, **kwargs) +attribute posthog.ai.gemini.gemini_async.AsyncClient.models = AsyncModels(provider_client=(self._provider_client), posthog_client=(self._ph_client), posthog_distinct_id=posthog_distinct_id, posthog_properties=posthog_properties, posthog_privacy_mode=posthog_privacy_mode, posthog_groups=posthog_groups, posthog_options=posthog_options, **kwargs) attribute posthog.ai.gemini.gemini_converter.GeminiMessage.content: Union[str, List[Any]] attribute posthog.ai.gemini.gemini_converter.GeminiMessage.parts: List[Union[GeminiPart, Dict[str, Any]]] attribute posthog.ai.gemini.gemini_converter.GeminiMessage.role: str @@ -617,6 +603,7 @@ attribute posthog.ai.gemini.genai = _GenAI() attribute posthog.ai.langchain.callbacks.GenerationMetadata.base_url: Optional[str] = None attribute posthog.ai.langchain.callbacks.GenerationMetadata.model: Optional[str] = None attribute posthog.ai.langchain.callbacks.GenerationMetadata.model_params: Optional[Dict[str, Any]] = None +attribute posthog.ai.langchain.callbacks.GenerationMetadata.posthog_options: Optional[Dict[str, Any]] = None attribute posthog.ai.langchain.callbacks.GenerationMetadata.posthog_properties: Optional[Dict[str, Any]] = None attribute posthog.ai.langchain.callbacks.GenerationMetadata.provider: Optional[str] = None attribute posthog.ai.langchain.callbacks.GenerationMetadata.tools: Optional[List[Dict[str, Any]]] = None @@ -722,6 +709,7 @@ attribute posthog.ai.types.StreamingEventData.groups: Optional[Dict[str, Any]] attribute posthog.ai.types.StreamingEventData.kwargs: Dict[str, Any] attribute posthog.ai.types.StreamingEventData.latency: float attribute posthog.ai.types.StreamingEventData.model: str +attribute posthog.ai.types.StreamingEventData.options: NotRequired[Optional[Dict[str, Any]]] attribute posthog.ai.types.StreamingEventData.privacy_mode: bool attribute posthog.ai.types.StreamingEventData.properties: Optional[Dict[str, Any]] attribute posthog.ai.types.StreamingEventData.provider: str @@ -747,21 +735,23 @@ attribute posthog.args.OptionalCaptureArgs.disable_geoip: NotRequired[Optional[b attribute posthog.args.OptionalCaptureArgs.distinct_id: NotRequired[Optional[ID_TYPES]] attribute posthog.args.OptionalCaptureArgs.flags: NotRequired[Optional[FeatureFlagEvaluations]] attribute posthog.args.OptionalCaptureArgs.groups: NotRequired[Optional[Dict[str, str]]] +attribute posthog.args.OptionalCaptureArgs.options: NotRequired[Optional[Dict[str, Any]]] attribute posthog.args.OptionalCaptureArgs.properties: NotRequired[Optional[Dict[str, Any]]] attribute posthog.args.OptionalCaptureArgs.send_feature_flags: NotRequired[Optional[Union[bool, SendFeatureFlagsOptions]]] attribute posthog.args.OptionalCaptureArgs.timestamp: NotRequired[Optional[Union[datetime, str]]] attribute posthog.args.OptionalCaptureArgs.uuid: NotRequired[Optional[Union[str, UUID]]] attribute posthog.args.OptionalSetArgs.disable_geoip: NotRequired[Optional[bool]] attribute posthog.args.OptionalSetArgs.distinct_id: NotRequired[Optional[ID_TYPES]] +attribute posthog.args.OptionalSetArgs.options: NotRequired[Optional[Dict[str, Any]]] attribute posthog.args.OptionalSetArgs.properties: NotRequired[Optional[Dict[str, Any]]] attribute posthog.args.OptionalSetArgs.timestamp: NotRequired[Optional[Union[datetime, str]]] attribute posthog.args.OptionalSetArgs.uuid: NotRequired[Optional[Union[str, UUID]]] attribute posthog.async_client.AsyncClient.api_key = (project_api_key or '').strip() attribute posthog.async_client.AsyncClient.app_host = app_host attribute posthog.async_client.AsyncClient.before_send = before_send -attribute posthog.async_client.AsyncClient.capture_compression = _resolve_capture_compression(capture_compression, gzip_fallback=gzip) +attribute posthog.async_client.AsyncClient.capture_ai_compression = _resolve_capture_ai_compression(capture_ai_compression) +attribute posthog.async_client.AsyncClient.capture_compression = _resolve_capture_compression(capture_compression) attribute posthog.async_client.AsyncClient.capture_exception_code_variables = capture_exception_code_variables -attribute posthog.async_client.AsyncClient.capture_mode = _resolve_capture_mode(capture_mode) attribute posthog.async_client.AsyncClient.capture_trace_context = capture_trace_context attribute posthog.async_client.AsyncClient.code_variables_detect_secrets = code_variables_detect_secrets if code_variables_detect_secrets is not None else DEFAULT_CODE_VARIABLES_DETECT_SECRETS attribute posthog.async_client.AsyncClient.code_variables_ignore_patterns = code_variables_ignore_patterns if code_variables_ignore_patterns is not None else DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS @@ -769,14 +759,14 @@ attribute posthog.async_client.AsyncClient.code_variables_mask_patterns = code_v attribute posthog.async_client.AsyncClient.code_variables_mask_url_credentials = code_variables_mask_url_credentials if code_variables_mask_url_credentials is not None else DEFAULT_CODE_VARIABLES_MASK_URL_CREDENTIALS attribute posthog.async_client.AsyncClient.debug = debug attribute posthog.async_client.AsyncClient.disable_geoip = disable_geoip -attribute posthog.async_client.AsyncClient.disabled = disabled or not self.api_key +attribute posthog.async_client.AsyncClient.disabled = disabled or not self.api_key or _is_personal_api_key(self.api_key) attribute posthog.async_client.AsyncClient.distinct_ids_feature_flags_reported = SizeLimitedDict(_MAX_DICT_SIZE, set) attribute posthog.async_client.AsyncClient.email_request_max_retries = email_request_max_retries attribute posthog.async_client.AsyncClient.email_request_timeout_seconds = email_request_timeout_seconds attribute posthog.async_client.AsyncClient.emails: AsyncEmails +attribute posthog.async_client.AsyncClient.enable_full_ai_capture = enable_full_ai_capture is True attribute posthog.async_client.AsyncClient.feature_flags_request_max_retries = max(0, feature_flags_request_max_retries) attribute posthog.async_client.AsyncClient.feature_flags_request_timeout_seconds = feature_flags_request_timeout_seconds -attribute posthog.async_client.AsyncClient.gzip = gzip attribute posthog.async_client.AsyncClient.historical_migration = historical_migration attribute posthog.async_client.AsyncClient.host = determine_server_host(host) attribute posthog.async_client.AsyncClient.in_app_modules = in_app_modules @@ -787,10 +777,12 @@ attribute posthog.async_client.AsyncClient.max_retries = max(0, max_retries) attribute posthog.async_client.AsyncClient.migrated_from = migrated_from attribute posthog.async_client.AsyncClient.on_error = on_error attribute posthog.async_client.AsyncClient.personal_api_key = self.secret_key +attribute posthog.async_client.AsyncClient.privacy_mode = privacy_mode attribute posthog.async_client.AsyncClient.project_root = os.getcwd() attribute posthog.async_client.AsyncClient.raw_host = normalize_host(host) attribute posthog.async_client.AsyncClient.secret_key = (resolved_secret_key.strip() if isinstance(resolved_secret_key, str) else resolved_secret_key) or None attribute posthog.async_client.AsyncClient.send = send +attribute posthog.async_client.AsyncClient.super_options = super_options attribute posthog.async_client.AsyncClient.super_properties = super_properties attribute posthog.async_client.AsyncClient.timeout = timeout attribute posthog.before_send = None @@ -802,21 +794,25 @@ attribute posthog.capture_compression.CaptureCompression.DEFLATE = 'deflate' attribute posthog.capture_compression.CaptureCompression.GZIP = 'gzip' attribute posthog.capture_compression.CaptureCompression.NONE = 'none' attribute posthog.capture_compression.CaptureCompression.ZSTD = 'zstd' +attribute posthog.capture_event.log = logging.getLogger('posthog') attribute posthog.capture_exception_code_variables = False -attribute posthog.capture_mode.CAPTURE_MODE_ENV_VAR = 'POSTHOG_CAPTURE_MODE' -attribute posthog.capture_mode.CaptureMode.V0 = 'v0' -attribute posthog.capture_mode.CaptureMode.V1 = 'v1' +attribute posthog.capture_send.CaptureDroppedEvent.details: Optional[str] = None +attribute posthog.capture_send.CaptureDroppedEvent.uuid: str +attribute posthog.capture_send.CaptureError.attempts = attempts +attribute posthog.capture_send.CaptureError.drops = [(CaptureDroppedEvent(*drop)) for drop in (drops or [])] +attribute posthog.capture_send.CaptureError.endpoint = endpoint +attribute posthog.capture_send.CaptureError.event_results = event_results or {} +attribute posthog.capture_send.CaptureError.request_id = request_id +attribute posthog.capture_send.CaptureError.retry_exhausted = retry_exhausted or [] +attribute posthog.capture_send.CaptureEventResult.details: Optional[str] = None +attribute posthog.capture_send.CaptureEventResult.result: Optional[str] attribute posthog.capture_trace_context = False -attribute posthog.capture_v1.CaptureV1Error.attempts = attempts -attribute posthog.capture_v1.CaptureV1Error.drops = drops or [] -attribute posthog.capture_v1.CaptureV1Error.request_id = request_id -attribute posthog.capture_v1.CaptureV1Error.retry_exhausted = retry_exhausted or [] attribute posthog.client.Client.api_key = (project_api_key or '').strip() attribute posthog.client.Client.app_host = app_host attribute posthog.client.Client.before_send = before_send -attribute posthog.client.Client.capture_compression = _resolve_capture_compression(capture_compression, gzip_fallback=gzip) +attribute posthog.client.Client.capture_ai_compression = _resolve_capture_ai_compression(capture_ai_compression) +attribute posthog.client.Client.capture_compression = _resolve_capture_compression(capture_compression) attribute posthog.client.Client.capture_exception_code_variables = capture_exception_code_variables -attribute posthog.client.Client.capture_mode = _resolve_capture_mode(capture_mode) attribute posthog.client.Client.capture_trace_context = capture_trace_context attribute posthog.client.Client.code_variables_detect_secrets = code_variables_detect_secrets if code_variables_detect_secrets is not None else DEFAULT_CODE_VARIABLES_DETECT_SECRETS attribute posthog.client.Client.code_variables_ignore_patterns = code_variables_ignore_patterns if code_variables_ignore_patterns is not None else DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS @@ -826,7 +822,7 @@ attribute posthog.client.Client.cohorts: Optional[dict[str, Any]] = None attribute posthog.client.Client.consumers: Optional[List[Consumer]] attribute posthog.client.Client.debug = debug attribute posthog.client.Client.disable_geoip = disable_geoip -attribute posthog.client.Client.disabled = disabled or not self.api_key +attribute posthog.client.Client.disabled = disabled or not self.api_key or _is_personal_api_key(self.api_key) attribute posthog.client.Client.distinct_ids_feature_flags_reported = SizeLimitedDict(MAX_DICT_SIZE, set) attribute posthog.client.Client.email_request_max_retries = email_request_max_retries attribute posthog.client.Client.email_request_timeout_seconds = email_request_timeout_seconds @@ -847,7 +843,6 @@ attribute posthog.client.Client.flag_cache = self._initialize_flag_cache(flag_fa attribute posthog.client.Client.flag_definition_version = 0 attribute posthog.client.Client.flag_fallback_cache_url = flag_fallback_cache_url attribute posthog.client.Client.group_type_mapping: Optional[dict[str, str]] = None -attribute posthog.client.Client.gzip = gzip attribute posthog.client.Client.historical_migration = historical_migration attribute posthog.client.Client.host = determine_server_host(host) attribute posthog.client.Client.in_app_modules = in_app_modules @@ -867,6 +862,7 @@ attribute posthog.client.Client.queue: Queue attribute posthog.client.Client.raw_host = normalize_host(host) attribute posthog.client.Client.secret_key = (resolved_secret_key.strip() if isinstance(resolved_secret_key, str) else resolved_secret_key) or None attribute posthog.client.Client.send = send +attribute posthog.client.Client.super_options = super_options attribute posthog.client.Client.super_properties = super_properties attribute posthog.client.Client.sync_mode = sync_mode attribute posthog.client.Client.timeout = timeout @@ -875,16 +871,16 @@ attribute posthog.code_variables_detect_secrets = DEFAULT_CODE_VARIABLES_DETECT_ attribute posthog.code_variables_ignore_patterns = DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS attribute posthog.code_variables_mask_patterns = DEFAULT_CODE_VARIABLES_MASK_PATTERNS attribute posthog.code_variables_mask_url_credentials = DEFAULT_CODE_VARIABLES_MASK_URL_CREDENTIALS -attribute posthog.consumer.AI_MAX_MSG_SIZE = 8 * 1024 * 1024 +attribute posthog.consumer.AI_ENVELOPE_HEADROOM = 64 * 1024 +attribute posthog.consumer.AI_MAX_MSG_SIZE = AI_MAX_PROPERTIES_SIZE + AI_ENVELOPE_HEADROOM +attribute posthog.consumer.AI_MAX_PROPERTIES_SIZE = 8 * 1024 * 1024 attribute posthog.consumer.BATCH_SIZE_LIMIT = 5 * 1024 * 1024 attribute posthog.consumer.Consumer.api_key = api_key attribute posthog.consumer.Consumer.capture_compression = capture_compression -attribute posthog.consumer.Consumer.capture_mode = capture_mode attribute posthog.consumer.Consumer.daemon = True attribute posthog.consumer.Consumer.endpoint = endpoint attribute posthog.consumer.Consumer.flush_at = flush_at attribute posthog.consumer.Consumer.flush_interval = flush_interval -attribute posthog.consumer.Consumer.gzip = gzip attribute posthog.consumer.Consumer.historical_migration = historical_migration attribute posthog.consumer.Consumer.host = host attribute posthog.consumer.Consumer.log = logging.getLogger('posthog') @@ -894,7 +890,7 @@ attribute posthog.consumer.Consumer.queue = queue attribute posthog.consumer.Consumer.retries = max(0, retries) attribute posthog.consumer.Consumer.running = True attribute posthog.consumer.Consumer.timeout = timeout -attribute posthog.consumer.MAX_MSG_SIZE = 900 * 1024 +attribute posthog.consumer.MAX_MSG_SIZE = 10 * 1024 * 1024 attribute posthog.contexts.ContextScope.capture_exception_code_variables: Optional[bool] = None attribute posthog.contexts.ContextScope.capture_exceptions = capture_exceptions attribute posthog.contexts.ContextScope.client: Optional[Client] = client @@ -905,6 +901,7 @@ attribute posthog.contexts.ContextScope.code_variables_mask_url_credentials: Opt attribute posthog.contexts.ContextScope.device_id: Optional[str] = None attribute posthog.contexts.ContextScope.distinct_id: Optional[str] = None attribute posthog.contexts.ContextScope.fresh = fresh +attribute posthog.contexts.ContextScope.options: Dict[str, Any] = {} attribute posthog.contexts.ContextScope.parent = parent attribute posthog.contexts.ContextScope.session_id: Optional[str] = None attribute posthog.contexts.ContextScope.tags: Dict[str, Any] = {} @@ -1134,6 +1131,7 @@ attribute posthog.mcp.types.MCPAnalyticsOptions.collect_feedback: Union[bool, Co attribute posthog.mcp.types.MCPAnalyticsOptions.context: Union[bool, MCPAnalyticsContextOptions] = True attribute posthog.mcp.types.MCPAnalyticsOptions.enable_conversation_id: bool = True attribute posthog.mcp.types.MCPAnalyticsOptions.enable_exception_autocapture: bool = True +attribute posthog.mcp.types.MCPAnalyticsOptions.event_options: Optional[EventOptionsFn] = None attribute posthog.mcp.types.MCPAnalyticsOptions.event_properties: Optional[EventPropertiesFn] = None attribute posthog.mcp.types.MCPAnalyticsOptions.identify: Optional[Union[IdentifyFn, UserIdentity]] = None attribute posthog.mcp.types.MCPAnalyticsOptions.intent_fallback: Optional[IntentFallbackFn] = None @@ -1180,14 +1178,12 @@ attribute posthog.privacy_mode = False attribute posthog.project_api_key = None attribute posthog.project_root = None attribute posthog.release_id.RELEASE_ID_ENV_VAR = 'POSTHOG_RELEASE_ID' -attribute posthog.request.AI_EVENTS_ENDPOINT = '/i/v0/ai/batch/' attribute posthog.request.APIError.message = message attribute posthog.request.APIError.retry_after = retry_after attribute posthog.request.APIError.status = status attribute posthog.request.DEFAULT_HOST = US_INGESTION_ENDPOINT attribute posthog.request.EU_APP_ENDPOINT = 'https://eu.posthog.com' attribute posthog.request.EU_INGESTION_ENDPOINT = 'https://eu.i.posthog.com' -attribute posthog.request.EVENTS_ENDPOINT = '/batch/' attribute posthog.request.GetResponse.data: Any attribute posthog.request.GetResponse.etag: Optional[str] = None attribute posthog.request.GetResponse.not_modified: bool = False @@ -1204,6 +1200,7 @@ attribute posthog.request.US_APP_ENDPOINT = 'https://us.posthog.com' attribute posthog.request.US_INGESTION_ENDPOINT = 'https://us.i.posthog.com' attribute posthog.secret_key = None attribute posthog.send = True +attribute posthog.super_options = None attribute posthog.super_properties = None attribute posthog.sync_mode = False attribute posthog.traces = None @@ -1285,8 +1282,8 @@ class posthog.ai.anthropic.anthropic_providers.AnthropicBedrock(posthog_client: class posthog.ai.anthropic.anthropic_providers.AnthropicVertex(posthog_client: Optional[PostHogClient] = None, **kwargs) class posthog.ai.anthropic.anthropic_providers.AsyncAnthropicBedrock(posthog_client: Optional[PostHogClient] = None, **kwargs) class posthog.ai.anthropic.anthropic_providers.AsyncAnthropicVertex(posthog_client: Optional[PostHogClient] = None, **kwargs) -class posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient(options: Optional[ClaudeAgentOptions] = None, transport: Any = None, *, posthog_client: Optional[Client] = None, posthog_distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None) -class posthog.ai.claude_agent_sdk.processor.PostHogClaudeAgentProcessor(client: Optional[Client] = None, distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None) +class posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient(options: Optional[ClaudeAgentOptions] = None, transport: Any = None, *, posthog_client: Optional[Client] = None, posthog_distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None) +class posthog.ai.claude_agent_sdk.processor.PostHogClaudeAgentProcessor(client: Optional[Client] = None, distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None, options: Optional[Dict[str, Any]] = None) class posthog.ai.evaluations.AsyncDatasetSnapshot(dataset: Dataset, revision: int, revision_id: str, _datasets: AsyncDatasets) class posthog.ai.evaluations.AsyncDatasets(transport: AsyncTransport, project_id: int) class posthog.ai.evaluations.AsyncExperiment(transport: AsyncTransport, project_id: int, id: str, *, receipt: ExperimentReceipt | None = None, submission: bytes | None = None) @@ -1327,17 +1324,17 @@ class posthog.ai.evaluations.ScorerVersion(id: str, definition_id: str, version: class posthog.ai.evaluations.ScorerVersionPage(count: int, results: tuple[ScorerVersion[ScorerConfig], ...], next_cursor: str | None) class posthog.ai.evaluations.Scorers(transport: SyncTransport, project_id: int) class posthog.ai.evaluations.UploadReceipt(items: tuple[ItemReceipt, ...], results: tuple[ResultReceipt, ...]) -class posthog.ai.gemini.gemini.Client(api_key: Optional[str] = None, vertexai: Optional[bool] = None, credentials: Optional[Any] = None, project: Optional[str] = None, location: Optional[str] = None, debug_config: Optional[Any] = None, http_options: Optional[Any] = None, posthog_client: Optional[PostHogClient] = None, posthog_distinct_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs) -class posthog.ai.gemini.gemini.Models(api_key: Optional[str] = None, vertexai: Optional[bool] = None, credentials: Optional[Any] = None, project: Optional[str] = None, location: Optional[str] = None, debug_config: Optional[Any] = None, http_options: Optional[Any] = None, posthog_client: Optional[PostHogClient] = None, posthog_distinct_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, provider_client: Optional[Any] = None, **kwargs) -class posthog.ai.gemini.gemini_async.AsyncClient(api_key: Optional[str] = None, vertexai: Optional[bool] = None, credentials: Optional[Any] = None, project: Optional[str] = None, location: Optional[str] = None, debug_config: Optional[Any] = None, http_options: Optional[Any] = None, posthog_client: Optional[PostHogClient] = None, posthog_distinct_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs) -class posthog.ai.gemini.gemini_async.AsyncModels(api_key: Optional[str] = None, vertexai: Optional[bool] = None, credentials: Optional[Any] = None, project: Optional[str] = None, location: Optional[str] = None, debug_config: Optional[Any] = None, http_options: Optional[Any] = None, posthog_client: Optional[PostHogClient] = None, posthog_distinct_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, provider_client: Optional[Any] = None, **kwargs) +class posthog.ai.gemini.gemini.Client(api_key: Optional[str] = None, vertexai: Optional[bool] = None, credentials: Optional[Any] = None, project: Optional[str] = None, location: Optional[str] = None, debug_config: Optional[Any] = None, http_options: Optional[Any] = None, posthog_client: Optional[PostHogClient] = None, posthog_distinct_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs) +class posthog.ai.gemini.gemini.Models(api_key: Optional[str] = None, vertexai: Optional[bool] = None, credentials: Optional[Any] = None, project: Optional[str] = None, location: Optional[str] = None, debug_config: Optional[Any] = None, http_options: Optional[Any] = None, posthog_client: Optional[PostHogClient] = None, posthog_distinct_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, provider_client: Optional[Any] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs) +class posthog.ai.gemini.gemini_async.AsyncClient(api_key: Optional[str] = None, vertexai: Optional[bool] = None, credentials: Optional[Any] = None, project: Optional[str] = None, location: Optional[str] = None, debug_config: Optional[Any] = None, http_options: Optional[Any] = None, posthog_client: Optional[PostHogClient] = None, posthog_distinct_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs) +class posthog.ai.gemini.gemini_async.AsyncModels(api_key: Optional[str] = None, vertexai: Optional[bool] = None, credentials: Optional[Any] = None, project: Optional[str] = None, location: Optional[str] = None, debug_config: Optional[Any] = None, http_options: Optional[Any] = None, posthog_client: Optional[PostHogClient] = None, posthog_distinct_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, provider_client: Optional[Any] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs) class posthog.ai.gemini.gemini_converter.GeminiMessage class posthog.ai.gemini.gemini_converter.GeminiPart -class posthog.ai.langchain.callbacks.CallbackHandler(client: Optional[Client] = None, *, distinct_id: Optional[Union[str, int, UUID]] = None, trace_id: Optional[Union[str, int, float, UUID]] = None, properties: Optional[Dict[str, Any]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None) -class posthog.ai.langchain.callbacks.GenerationMetadata(name: str, start_time: float, end_time: Optional[float], input: Optional[Any], provider: Optional[str] = None, model: Optional[str] = None, model_params: Optional[Dict[str, Any]] = None, base_url: Optional[str] = None, tools: Optional[List[Dict[str, Any]]] = None, posthog_properties: Optional[Dict[str, Any]] = None) +class posthog.ai.langchain.callbacks.CallbackHandler(client: Optional[Client] = None, *, distinct_id: Optional[Union[str, int, UUID]] = None, trace_id: Optional[Union[str, int, float, UUID]] = None, properties: Optional[Dict[str, Any]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, options: Optional[Dict[str, Any]] = None) +class posthog.ai.langchain.callbacks.GenerationMetadata(name: str, start_time: float, end_time: Optional[float], input: Optional[Any], provider: Optional[str] = None, model: Optional[str] = None, model_params: Optional[Dict[str, Any]] = None, base_url: Optional[str] = None, tools: Optional[List[Dict[str, Any]]] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None) class posthog.ai.langchain.callbacks.ModelUsage(input_tokens: Optional[int], output_tokens: Optional[int], cache_write_tokens: Optional[int], cache_read_tokens: Optional[int], reasoning_tokens: Optional[int], cache_write_5m_tokens: Optional[int] = None, cache_write_1h_tokens: Optional[int] = None, web_search_count: Optional[int] = None) class posthog.ai.langchain.callbacks.SpanMetadata(name: str, start_time: float, end_time: Optional[float], input: Optional[Any]) -class posthog.ai.langchain.middleware.PostHogMiddleware(client: Optional[Client] = None, *, distinct_id: Optional[Union[str, int, UUID]] = None, trace_id: Optional[Union[str, int, float, UUID]] = None, properties: Optional[dict[str, Any]] = None, privacy_mode: bool = False, groups: Optional[dict[str, Any]] = None) +class posthog.ai.langchain.middleware.PostHogMiddleware(client: Optional[Client] = None, *, distinct_id: Optional[Union[str, int, UUID]] = None, trace_id: Optional[Union[str, int, float, UUID]] = None, properties: Optional[dict[str, Any]] = None, privacy_mode: bool = False, groups: Optional[dict[str, Any]] = None, options: Optional[dict[str, Any]] = None) class posthog.ai.openai.openai.OpenAI(posthog_client: Optional[PostHogClient] = None, **kwargs) class posthog.ai.openai.openai.WrappedBeta class posthog.ai.openai.openai.WrappedBetaChat @@ -1356,7 +1353,7 @@ class posthog.ai.openai.openai_async.WrappedEmbeddings class posthog.ai.openai.openai_async.WrappedResponses class posthog.ai.openai.openai_providers.AsyncAzureOpenAI(posthog_client: Optional[PostHogClient] = None, **kwargs) class posthog.ai.openai.openai_providers.AzureOpenAI(posthog_client: Optional[PostHogClient] = None, **kwargs) -class posthog.ai.openai_agents.processor.PostHogTracingProcessor(client: Optional[Client] = None, distinct_id: Optional[Union[str, Callable[[Trace], Optional[str]]]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None) +class posthog.ai.openai_agents.processor.PostHogTracingProcessor(client: Optional[Client] = None, distinct_id: Optional[Union[str, Callable[[Trace], Optional[str]]]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None, options: Optional[Dict[str, Any]] = None) class posthog.ai.otel.exporter.PostHogTraceExporter(api_key: str, host: str = DEFAULT_HOST, *, privacy_mode: bool = False, client: Optional[Client] = None) class posthog.ai.otel.processor.PostHogSpanProcessor(api_key: str, host: str = DEFAULT_HOST, *, privacy_mode: bool = False, client: Optional[Client] = None) class posthog.ai.prompts.CachedPrompt(prompt: str, fetched_at: float, name: str, version: int, label: Optional[str] = None, config: Optional[Dict[str, Any]] = None) @@ -1375,14 +1372,15 @@ class posthog.ai.types.TokenUsage class posthog.ai.types.ToolInProgress class posthog.args.OptionalCaptureArgs class posthog.args.OptionalSetArgs -class posthog.async_client.AsyncClient(project_api_key: str, host: Optional[str] = None, debug: bool = False, max_queue_size: int = 10000, send: bool = True, on_error=None, flush_at: int = 100, flush_interval: float = 5.0, gzip: bool = False, max_retries: int = 3, timeout: float = 15, thread: int = 1, disabled: bool = False, disable_geoip: bool = True, is_server: bool = True, historical_migration: bool = False, super_properties: Optional[dict[str, Any]] = None, before_send=None, log_captured_exceptions: bool = False, project_root: Optional[str] = None, capture_exception_code_variables: bool = False, code_variables_mask_patterns=None, code_variables_ignore_patterns=None, code_variables_mask_url_credentials=None, code_variables_detect_secrets=None, in_app_modules: Optional[list[str]] = None, capture_mode: Optional[Union[CaptureMode, str]] = None, capture_compression: Optional[Union[CaptureCompression, str]] = None, capture_trace_context: bool = False, secret_key: Optional[str] = None, personal_api_key: Optional[str] = None, feature_flags_request_timeout_seconds: float = 3, feature_flags_request_max_retries: int = 1, app_host: Optional[str] = None, email_request_timeout_seconds: float = 15, email_request_max_retries: int = 2, migrated_from: Optional[str] = None) +class posthog.async_client.AsyncClient(project_api_key: str, host: Optional[str] = None, *, debug: bool = False, max_queue_size: int = 10000, send: bool = True, on_error=None, flush_at: int = 100, flush_interval: float = 5.0, max_retries: int = 3, timeout: float = 15, thread: int = 1, disabled: bool = False, disable_geoip: bool = True, is_server: bool = True, historical_migration: bool = False, super_properties: Optional[dict[str, Any]] = None, super_options: Optional[dict[str, Any]] = None, before_send=None, log_captured_exceptions: bool = False, project_root: Optional[str] = None, capture_exception_code_variables: bool = False, code_variables_mask_patterns=None, code_variables_ignore_patterns=None, code_variables_mask_url_credentials=None, code_variables_detect_secrets=None, in_app_modules: Optional[list[str]] = None, capture_compression: Optional[Union[CaptureCompression, str]] = None, capture_ai_compression: Optional[Union[CaptureCompression, str]] = None, capture_ai_max_queue_size: int = 1000, capture_ai_timeout: float = 30, capture_ai_max_event_bytes: int = AI_MAX_MSG_SIZE, privacy_mode: bool = False, enable_full_ai_capture: bool = False, capture_trace_context: bool = False, secret_key: Optional[str] = None, personal_api_key: Optional[str] = None, feature_flags_request_timeout_seconds: float = 3, feature_flags_request_max_retries: int = 1, app_host: Optional[str] = None, email_request_timeout_seconds: float = 15, email_request_max_retries: int = 2, migrated_from: Optional[str] = None) class posthog.async_client.AsyncPosthog class posthog.bucketed_rate_limiter.BucketedRateLimiter(bucket_size: Number, refill_rate: Number, refill_interval_seconds: Number, on_bucket_rate_limited: Optional[Callable[[Hashable], None]] = None, clock: Callable[[], float] = time.monotonic) class posthog.capture_compression.CaptureCompression -class posthog.capture_mode.CaptureMode -class posthog.capture_v1.CaptureV1Error(status: int | str, message: str, *, retry_after: Optional[float] = None, request_id: Optional[str] = None, attempts: Optional[int] = None, retry_exhausted: Optional[list[str]] = None, drops: Optional[list[tuple[str, Optional[str]]]] = None) -class posthog.client.Client(project_api_key: str, host=None, debug=False, max_queue_size=10000, send=True, on_error=None, flush_at=100, flush_interval=5.0, gzip=False, max_retries=3, sync_mode=False, timeout: float = 15, thread=1, poll_interval=30, personal_api_key=None, disabled=False, disable_geoip=True, is_server=True, historical_migration=False, feature_flags_request_timeout_seconds: float = 3, feature_flags_request_max_retries=1, super_properties=None, enable_exception_autocapture=False, log_captured_exceptions=False, project_root=None, privacy_mode=False, before_send=None, flag_fallback_cache_url=None, enable_local_evaluation=True, flag_definition_cache_provider: Optional[FlagDefinitionCacheProvider] = None, capture_exception_code_variables=False, code_variables_mask_patterns=None, code_variables_ignore_patterns=None, code_variables_mask_url_credentials=None, code_variables_detect_secrets=None, in_app_modules: list[str] | None = None, enable_exception_autocapture_rate_limiting=False, exception_autocapture_bucket_size=ExceptionCapture.DEFAULT_BUCKET_SIZE, exception_autocapture_refill_rate=ExceptionCapture.DEFAULT_REFILL_RATE, exception_autocapture_refill_interval_seconds=ExceptionCapture.DEFAULT_REFILL_INTERVAL_SECONDS, capture_mode: Optional[Union[CaptureMode, str]] = None, capture_compression: Optional[Union[CaptureCompression, str]] = None, secret_key=None, metrics: Optional[dict] = None, enable_full_ai_capture=False, capture_trace_context=False, _use_ai_lane=False, _enable_multimodal_capture=False, traces: Optional[dict] = None, app_host: Optional[str] = None, email_request_timeout_seconds: float = 15, email_request_max_retries: int = 2, migrated_from: Optional[str] = None) -class posthog.consumer.Consumer(queue, api_key, flush_at=100, host=None, on_error=None, flush_interval=5.0, gzip=False, retries=10, timeout: float = 15, historical_migration=False, endpoint=EVENTS_ENDPOINT, max_msg_size=MAX_MSG_SIZE, capture_mode=CaptureMode.V0, capture_compression=CaptureCompression.NONE) +class posthog.capture_send.CaptureDroppedEvent +class posthog.capture_send.CaptureError(status: int | str, message: str, *, endpoint: str, retry_after: Optional[float] = None, request_id: Optional[str] = None, attempts: Optional[int] = None, retry_exhausted: Optional[list[str]] = None, drops: Optional[Sequence[tuple[str, Optional[str]]]] = None, event_results: Optional[dict[str, CaptureEventResult]] = None) +class posthog.capture_send.CaptureEventResult(result: Optional[str], details: Optional[str] = None) +class posthog.client.Client(project_api_key: str, host=None, *, debug=False, max_queue_size=10000, send=True, on_error=None, flush_at=100, flush_interval=5.0, max_retries=3, sync_mode=False, timeout: float = 15, thread=1, poll_interval=30, personal_api_key=None, disabled=False, disable_geoip=True, is_server=True, historical_migration=False, feature_flags_request_timeout_seconds: float = 3, feature_flags_request_max_retries=1, super_properties=None, super_options=None, enable_exception_autocapture=False, log_captured_exceptions=False, project_root=None, privacy_mode=False, before_send=None, flag_fallback_cache_url=None, enable_local_evaluation=True, flag_definition_cache_provider: Optional[FlagDefinitionCacheProvider] = None, capture_exception_code_variables=False, code_variables_mask_patterns=None, code_variables_ignore_patterns=None, code_variables_mask_url_credentials=None, code_variables_detect_secrets=None, in_app_modules: list[str] | None = None, enable_exception_autocapture_rate_limiting=False, exception_autocapture_bucket_size=ExceptionCapture.DEFAULT_BUCKET_SIZE, exception_autocapture_refill_rate=ExceptionCapture.DEFAULT_REFILL_RATE, exception_autocapture_refill_interval_seconds=ExceptionCapture.DEFAULT_REFILL_INTERVAL_SECONDS, capture_compression: Optional[Union[CaptureCompression, str]] = None, capture_ai_compression: Optional[Union[CaptureCompression, str]] = None, capture_ai_max_queue_size: int = 1000, capture_ai_timeout: float = 30, capture_ai_max_event_bytes: int = AI_MAX_MSG_SIZE, secret_key=None, metrics: Optional[dict] = None, enable_full_ai_capture=False, capture_trace_context=False, _use_ai_lane=False, _enable_multimodal_capture=False, traces: Optional[dict] = None, app_host: Optional[str] = None, email_request_timeout_seconds: float = 15, email_request_max_retries: int = 2, migrated_from: Optional[str] = None) +class posthog.consumer.Consumer(queue, api_key, flush_at=100, host=None, on_error=None, flush_interval=5.0, retries=3, timeout: float = 15, historical_migration=False, endpoint=_CAPTURE_V1_PATH, max_msg_size=MAX_MSG_SIZE, capture_compression=CaptureCompression.NONE) class posthog.contexts.ContextScope(parent=None, fresh: bool = False, capture_exceptions: bool = True, client: Optional[Client] = None) class posthog.emails.AsyncEmails(secret_key: Optional[str], *, host: Optional[str] = None, timeout: float = 15, max_retries: int = 2, disabled: bool = False, http_client: Any = None, migrated_from: Optional[str] = None) class posthog.emails.CodeEmailArgs @@ -1419,7 +1417,7 @@ class posthog.mcp.types.CollectFeedbackOptions(tool_name: Optional[str] = None, class posthog.mcp.types.FeedbackReport(feedback_type: str = 'other', summary: str = '', sentiment: Optional[str] = None, friction_points: Optional[str] = None, suggested_improvement: Optional[str] = None, details: Optional[str] = None, tool_name: Optional[str] = None, task_completed: Optional[bool] = None, extras: JsonRecord = dict(), raw: JsonRecord = dict()) class posthog.mcp.types.MCPAnalyticsContextOptions(description: Optional[str] = None) class posthog.mcp.types.MCPAnalyticsModelOptions(description: Optional[str] = None) -class posthog.mcp.types.MCPAnalyticsOptions(logger: Optional[LoggerFn] = None, report_missing: bool = False, missing_capability_tool_name: Optional[str] = None, enable_conversation_id: bool = True, enable_exception_autocapture: bool = True, context: Union[bool, MCPAnalyticsContextOptions] = True, identify: Optional[Union[IdentifyFn, UserIdentity]] = None, intent_fallback: Optional[IntentFallbackFn] = None, before_send: Optional[BeforeSendFn] = None, event_properties: Optional[EventPropertiesFn] = None, capture_model: Union[bool, MCPAnalyticsModelOptions] = True, collect_feedback: Union[bool, CollectFeedbackOptions] = False, server_build: Optional[str] = None, should_record_input_key: Optional[ShouldRecordInputKeyFn] = None, resolve_input_aliases: Optional[ResolveInputAliasesFn] = None, resolve_original_tool: Optional[Callable[[str], Any]] = None, send_initialize_event: bool = True, send_tools_list_event: bool = True) +class posthog.mcp.types.MCPAnalyticsOptions(logger: Optional[LoggerFn] = None, report_missing: bool = False, missing_capability_tool_name: Optional[str] = None, enable_conversation_id: bool = True, enable_exception_autocapture: bool = True, context: Union[bool, MCPAnalyticsContextOptions] = True, identify: Optional[Union[IdentifyFn, UserIdentity]] = None, intent_fallback: Optional[IntentFallbackFn] = None, before_send: Optional[BeforeSendFn] = None, event_properties: Optional[EventPropertiesFn] = None, capture_model: Union[bool, MCPAnalyticsModelOptions] = True, collect_feedback: Union[bool, CollectFeedbackOptions] = False, server_build: Optional[str] = None, should_record_input_key: Optional[ShouldRecordInputKeyFn] = None, resolve_input_aliases: Optional[ResolveInputAliasesFn] = None, resolve_original_tool: Optional[Callable[[str], Any]] = None, send_initialize_event: bool = True, send_tools_list_event: bool = True, event_options: Optional[EventOptionsFn] = None) class posthog.mcp.types.PreparedToolCall(args: Optional[JsonRecord] = None, intent: Optional[str] = None, intent_source: Optional[str] = None, is_missing_capability: bool = False, llm_model: Optional[str] = None, llm_model_source: Optional[MCPAnalyticsModelSource] = None, is_feedback: bool = False, feedback_report: Optional[FeedbackReport] = None, session_id: Optional[str] = None, conversation_id: Optional[str] = None, _conversation_state: Optional[PreparedConversationState] = None) class posthog.mcp.types.ToolInputOptions(should_record_input_key: Optional[ShouldRecordInputKeyFn] = None, input_aliases: Optional[InputAliasMap] = None) class posthog.mcp.types.UserIdentity(distinct_id: str, properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None) @@ -1462,8 +1460,8 @@ function posthog.ai.anthropic.anthropic_converter.handle_anthropic_text_delta(ev function posthog.ai.anthropic.anthropic_converter.handle_anthropic_tool_delta(event: Any, content_blocks: List[StreamingContentBlock], tools_in_progress: Dict[str, ToolInProgress]) -> None function posthog.ai.claude_agent_sdk.formatting.format_assistant_blocks(blocks: Any) -> List[Dict[str, Any]] function posthog.ai.claude_agent_sdk.formatting.format_tool_result_content(block: Any, ph_client: Any = None) -> Any -function posthog.ai.claude_agent_sdk.instrument(client: Optional[Client] = None, distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None) -> PostHogClaudeAgentProcessor -function posthog.ai.claude_agent_sdk.query(*, prompt: Any, options: Optional[ClaudeAgentOptions] = None, transport: Any = None, posthog_client: Optional[Client] = None, posthog_distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None) +function posthog.ai.claude_agent_sdk.instrument(client: Optional[Client] = None, distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None, options: Optional[Dict[str, Any]] = None) -> PostHogClaudeAgentProcessor +function posthog.ai.claude_agent_sdk.query(*, prompt: Any, options: Optional[ClaudeAgentOptions] = None, transport: Any = None, posthog_client: Optional[Client] = None, posthog_distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None) function posthog.ai.gateway.is_posthog_ai_gateway_url(base_url: Any) -> bool function posthog.ai.gateway.warn_if_posthog_ai_gateway(base_url: Any) -> None function posthog.ai.gateway.warn_if_posthog_ai_gateway_otel_attributes(attributes: Optional[Mapping[str, Any]]) -> None @@ -1501,7 +1499,7 @@ function posthog.ai.openai.openai_converter.format_openai_streaming_output(accum function posthog.ai.openai.wrapper_utils.merge_provider_override(posthog_properties: Optional[Dict[str, Any]], posthog_provider_override: Optional[str]) -> Optional[Dict[str, Any]] function posthog.ai.openai.wrapper_utils.reset_fallback_warnings() -> None function posthog.ai.openai.wrapper_utils.warn_on_fallback(wrapper_name: str, name: str) -> None -function posthog.ai.openai_agents.instrument(client: Optional[Client] = None, distinct_id: Optional[Union[str, Callable[[Trace], Optional[str]]]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None) -> PostHogTracingProcessor +function posthog.ai.openai_agents.instrument(client: Optional[Client] = None, distinct_id: Optional[Union[str, Callable[[Trace], Optional[str]]]] = None, privacy_mode: bool = False, groups: Optional[Dict[str, Any]] = None, properties: Optional[Dict[str, Any]] = None, options: Optional[Dict[str, Any]] = None) -> PostHogTracingProcessor function posthog.ai.otel.spans.is_ai_span(span: ReadableSpan) -> bool function posthog.ai.sanitization.redact_base64_data_url(value: Any) -> Any function posthog.ai.sanitization.redact_media(value: Any, max_string_len: Optional[int] = None, ph_client: Any = None) -> Any @@ -1511,8 +1509,8 @@ function posthog.ai.sanitization.sanitize_langchain(data: Any, ph_client: Any = function posthog.ai.sanitization.sanitize_messages(data: Any, provider: Optional[str] = None, ph_client: Any = None) -> Any function posthog.ai.sanitization.sanitize_openai(data: Any, ph_client: Any = None) -> Any function posthog.ai.sanitization.sanitize_openai_response(data: Any, ph_client: Any = None) -> Any -function posthog.ai.utils.call_llm_and_track_usage(posthog_distinct_id: Optional[str], ph_client: PostHogClient, provider: str, posthog_trace_id: Optional[str], posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], base_url: str, call_method: Callable[..., Any], **kwargs: Any) -> Any -function posthog.ai.utils.call_llm_and_track_usage_async(posthog_distinct_id: Optional[str], ph_client: PostHogClient, provider: str, posthog_trace_id: Optional[str], posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], base_url: str, call_async_method: Callable[..., Any], **kwargs: Any) -> Any +function posthog.ai.utils.call_llm_and_track_usage(posthog_distinct_id: Optional[str], ph_client: PostHogClient, provider: str, posthog_trace_id: Optional[str], posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], base_url: str, call_method: Callable[..., Any], *, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Any +function posthog.ai.utils.call_llm_and_track_usage_async(posthog_distinct_id: Optional[str], ph_client: PostHogClient, provider: str, posthog_trace_id: Optional[str], posthog_properties: Optional[Dict[str, Any]], posthog_privacy_mode: bool, posthog_groups: Optional[Dict[str, Any]], base_url: str, call_async_method: Callable[..., Any], *, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Any function posthog.ai.utils.capture_streaming_event(ph_client: PostHogClient, event_data: StreamingEventData) function posthog.ai.utils.extract_available_tool_calls(provider: str, kwargs: Dict[str, Any]) function posthog.ai.utils.extract_stop_reason(response: Any, provider: str) -> Optional[str] @@ -1524,10 +1522,10 @@ function posthog.ai.utils.merge_system_prompt(kwargs: Dict[str, Any], provider: function posthog.ai.utils.merge_usage_stats(target: TokenUsage, source: TokenUsage, mode: str = 'incremental') -> None function posthog.ai.utils.serialize_raw_usage(raw_usage: Any) -> Optional[Dict[str, Any]] function posthog.ai.utils.with_privacy_mode(ph_client: PostHogClient, privacy_mode: bool, value: Any) -function posthog.alias(previous_id: ID_TYPES, distinct_id: str, timestamp: Optional[Union[datetime.datetime, str]] = None, uuid: Optional[str] = None, disable_geoip: Optional[bool] = None) -> Optional[str] +function posthog.alias(previous_id: ID_TYPES, distinct_id: str, timestamp: Optional[Union[datetime.datetime, str]] = None, uuid: Optional[str] = None, disable_geoip: Optional[bool] = None, options: Optional[Dict[str, Any]] = None) -> Optional[str] function posthog.capture(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] function posthog.capture_ai(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] -function posthog.capture_exception(exception: Optional[ExceptionArg] = None, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] +function posthog.capture_exception(exception: Optional[ExceptionArg] = None, *, level: Optional[str] = None, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] function posthog.client.add_context_tags(properties) function posthog.client.get_identity_state(passed) -> tuple[str, bool] function posthog.client.no_throw(default_return=None) @@ -1539,6 +1537,7 @@ function posthog.contexts.get_code_variables_mask_patterns_context() -> Optional function posthog.contexts.get_code_variables_mask_url_credentials_context() -> Optional[bool] function posthog.contexts.get_context_device_id() -> Optional[str] function posthog.contexts.get_context_distinct_id() -> Optional[str] +function posthog.contexts.get_context_options() -> Dict[str, Any] function posthog.contexts.get_context_session_id() -> Optional[str] function posthog.contexts.get_tags() -> Dict[str, Any] function posthog.contexts.identify_context(distinct_id: str) -> None @@ -1550,6 +1549,7 @@ function posthog.contexts.set_code_variables_ignore_patterns_context(ignore_patt function posthog.contexts.set_code_variables_mask_patterns_context(mask_patterns: list) -> None function posthog.contexts.set_code_variables_mask_url_credentials_context(enabled: bool) -> None function posthog.contexts.set_context_device_id(device_id: str) -> None +function posthog.contexts.set_context_option(key: str, value: Any) -> None function posthog.contexts.set_context_session(session_id: str) -> None function posthog.contexts.tag(key: str, value: Any) -> None function posthog.evaluate_flags(distinct_id: Optional[ID_TYPES] = None, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys: Optional[list[str]] = None, device_id: Optional[str] = None) -> FeatureFlagEvaluations @@ -1604,6 +1604,7 @@ function posthog.flush(timeout_seconds: Optional[float] = 10) -> None function posthog.get_active_span() -> Optional[Span] function posthog.get_all_flags(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, flag_keys_to_evaluate: Optional[list[str]] = None) -> Optional[dict[str, FlagValue]] function posthog.get_all_flags_and_payloads(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, flag_keys_to_evaluate: Optional[list[str]] = None) -> FlagsAndPayloads +function posthog.get_context_options() -> Dict[str, Any] function posthog.get_feature_flag(key: str, distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[FlagValue] function posthog.get_feature_flag_evaluation_runtime(key: str) -> Optional[FeatureFlagEvaluationRuntime] function posthog.get_feature_flag_keys_by_evaluation_runtime(evaluation_runtime: Union[FeatureFlagEvaluationRuntime, str]) -> list[str] @@ -1611,7 +1612,7 @@ function posthog.get_feature_flag_payload(key: str, distinct_id: ID_TYPES, match function posthog.get_feature_flag_result(key: str, distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[FeatureFlagResult] function posthog.get_remote_config_payload(key: str) function posthog.get_tags() -> Dict[str, Any] -function posthog.group_identify(group_type: str, group_key: str, properties: Optional[Dict[str, Any]] = None, timestamp: Optional[Union[datetime.datetime, str]] = None, uuid: Optional[str] = None, disable_geoip: Optional[bool] = None, distinct_id: Optional[ID_TYPES] = None) -> Optional[str] +function posthog.group_identify(group_type: str, group_key: str, properties: Optional[Dict[str, Any]] = None, timestamp: Optional[Union[datetime.datetime, str]] = None, uuid: Optional[str] = None, disable_geoip: Optional[bool] = None, distinct_id: Optional[ID_TYPES] = None, options: Optional[Dict[str, Any]] = None) -> Optional[str] function posthog.identify_context(distinct_id: str) function posthog.integrations.django.markcoroutinefunction(func) function posthog.integrations.drf.create_exception_handler(handler: Optional[Callable[[Exception, Mapping[str, Any]], Any]] = None, *, client: Optional[Client] = None, capture_exceptions: Optional[bool] = None, capture_4xx: bool = False, exception_filter: Optional[Callable[[Exception, Any, Mapping[str, Any]], bool]] = None) -> Callable[[Exception, Mapping[str, Any]], Any] @@ -1633,15 +1634,14 @@ function posthog.mcp.session_token.encode_session_id(payload: SessionTokenPayloa function posthog.mcp.session_token.read_mcp_session_header(headers: Any) -> Optional[str] function posthog.mcp.tools.get_more_tools_result() -> Dict[str, Any] function posthog.new_context(fresh: bool = False, capture_exceptions: Optional[bool] = None, client: Optional[Client] = None) -function posthog.request.batch_post(api_key: str, host: Optional[str] = None, gzip: bool = False, timeout: float = 15, path: str = EVENTS_ENDPOINT, **kwargs) -> requests.Response function posthog.request.determine_app_host(host: Optional[str]) -> str function posthog.request.determine_server_host(host: Optional[str]) -> str function posthog.request.disable_connection_reuse() -> None function posthog.request.enable_keep_alive() -> None -function posthog.request.flags(api_key: str, host: Optional[str] = None, gzip: bool = False, timeout: float = 15, max_retries: int = 1, **kwargs) -> Any +function posthog.request.flags(api_key: str, host: Optional[str] = None, *, timeout: float = 15, max_retries: int = 1, **kwargs) -> Any function posthog.request.get(api_key: str, url: str, host: Optional[str] = None, timeout: Optional[float] = None, etag: Optional[str] = None) -> GetResponse function posthog.request.normalize_host(host: Optional[str]) -> str -function posthog.request.post(api_key: str, host: Optional[str] = None, path: Optional[str] = None, gzip: bool = False, timeout: float = 15, session: Optional[requests.Session] = None, **kwargs) -> requests.Response +function posthog.request.post(api_key: str, host: Optional[str] = None, path: Optional[str] = None, *, timeout: float = 15, session: Optional[requests.Session] = None, **kwargs) -> requests.Response function posthog.request.remote_config(personal_api_key: str, project_api_key: str, host: Optional[str] = None, key: str = '', timeout: float = 15) -> Any function posthog.request.reset_sessions() -> None function posthog.request.set_socket_options(socket_options: Optional[SocketOptions]) -> None @@ -1653,6 +1653,7 @@ function posthog.set_code_variables_ignore_patterns_context(ignore_patterns: lis function posthog.set_code_variables_mask_patterns_context(mask_patterns: list[str]) function posthog.set_code_variables_mask_url_credentials_context(enabled: bool) function posthog.set_context_device_id(device_id: str) +function posthog.set_context_option(key: str, value: Any) -> None function posthog.set_context_session(session_id: str) function posthog.set_once(**kwargs: Unpack[OptionalSetArgs]) -> Optional[str] function posthog.setup() -> Client @@ -1676,10 +1677,10 @@ function posthog.utils.str_iequals(value, comparand) function posthog.utils.str_istartswith(source, search) function posthog.utils.system_context() -> dict[str, Any] function posthog.utils.total_seconds(delta: timedelta) -> float -method posthog.ai.anthropic.anthropic.WrappedMessages.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) -method posthog.ai.anthropic.anthropic.WrappedMessages.stream(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) -method posthog.ai.anthropic.anthropic_async.AsyncWrappedMessages.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) -method posthog.ai.anthropic.anthropic_async.AsyncWrappedMessages.stream(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.anthropic.anthropic.WrappedMessages.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.anthropic.anthropic.WrappedMessages.stream(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.anthropic.anthropic_async.AsyncWrappedMessages.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.anthropic.anthropic_async.AsyncWrappedMessages.stream(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) method posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient.connect(prompt: Any = None) -> None method posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient.disconnect() -> None method posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient.interrupt() -> None @@ -1687,7 +1688,7 @@ method posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient.query(prompt: s method posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient.receive_response() method posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient.set_model(model: Optional[str] = None) -> None method posthog.ai.claude_agent_sdk.client.PostHogClaudeSDKClient.set_permission_mode(mode: str) -> None -method posthog.ai.claude_agent_sdk.processor.PostHogClaudeAgentProcessor.query(*, prompt: Any, options: Optional[ClaudeAgentOptions] = None, transport: Any = None, posthog_distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None) +method posthog.ai.claude_agent_sdk.processor.PostHogClaudeAgentProcessor.query(*, prompt: Any, options: Optional[ClaudeAgentOptions] = None, transport: Any = None, posthog_distinct_id: Optional[Union[str, Callable[[ResultMessage], Optional[str]]]] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None) method posthog.ai.evaluations.AsyncDatasetSnapshot.iter_items(*, page_size: int = 25) method posthog.ai.evaluations.AsyncDatasets.archive(dataset_id: str | UUID) method posthog.ai.evaluations.AsyncDatasets.archive_item(item_id: str | UUID, *, base_version: int) @@ -1759,12 +1760,12 @@ method posthog.ai.evaluations.Scorers.list(*, limit: int = 100, offset: int = 0, method posthog.ai.evaluations.Scorers.list_versions(scorer_id: str | UUID, *, limit: int = 50, cursor: str | None = None) method posthog.ai.evaluations.Scorers.update(scorer_id: str | UUID, *, name: str | _Omitted = _OMITTED, description: str | None | _Omitted = _OMITTED, archived: bool | _Omitted = _OMITTED, tags: Sequence[str] | _Omitted = _OMITTED) method posthog.ai.evaluations.Scorers.validate_composition(*, kind: ScorerKind, composition: ScorerComposition, config: ScorerConfig | None = None) -method posthog.ai.gemini.gemini.Models.embed_content(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) -method posthog.ai.gemini.gemini.Models.generate_content(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) -method posthog.ai.gemini.gemini.Models.generate_content_stream(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) -method posthog.ai.gemini.gemini_async.AsyncModels.embed_content(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) -method posthog.ai.gemini.gemini_async.AsyncModels.generate_content(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) -method posthog.ai.gemini.gemini_async.AsyncModels.generate_content_stream(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.gemini.gemini.Models.embed_content(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.gemini.gemini.Models.generate_content(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.gemini.gemini.Models.generate_content_stream(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.gemini.gemini_async.AsyncModels.embed_content(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.gemini.gemini_async.AsyncModels.generate_content(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.gemini.gemini_async.AsyncModels.generate_content_stream(model: str, contents, posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: Optional[bool] = None, posthog_groups: Optional[Dict[str, Any]] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) method posthog.ai.langchain.callbacks.CallbackHandler.on_agent_action(action: AgentAction, *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any) -> Any method posthog.ai.langchain.callbacks.CallbackHandler.on_agent_finish(finish: AgentFinish, *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any) -> Any method posthog.ai.langchain.callbacks.CallbackHandler.on_chain_end(outputs: Dict[str, Any], *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any) @@ -1789,18 +1790,18 @@ method posthog.ai.langchain.middleware.PostHogMiddleware.awrap_tool_call(request method posthog.ai.langchain.middleware.PostHogMiddleware.before_agent(state: _PostHogMiddlewareState, runtime: Any) -> dict[str, Any] method posthog.ai.langchain.middleware.PostHogMiddleware.wrap_model_call(request: ModelRequest[Any], handler: Callable[[ModelRequest[Any]], ModelResponse[Any]]) -> ModelResponse[Any] method posthog.ai.langchain.middleware.PostHogMiddleware.wrap_tool_call(request: ToolCallRequest, handler: Callable[[ToolCallRequest], ToolMessage | Command[Any]]) -> ToolMessage | Command[Any] -method posthog.ai.openai.openai.WrappedBetaCompletions.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai.WrappedCompletions.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai.WrappedCompletions.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai.WrappedEmbeddings.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai.WrappedResponses.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai.WrappedResponses.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai_async.WrappedBetaCompletions.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai_async.WrappedCompletions.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai_async.WrappedCompletions.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai_async.WrappedEmbeddings.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai_async.WrappedResponses.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) -method posthog.ai.openai.openai_async.WrappedResponses.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, **kwargs: Any) +method posthog.ai.openai.openai.WrappedBetaCompletions.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai.WrappedCompletions.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai.WrappedCompletions.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai.WrappedEmbeddings.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai.WrappedResponses.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai.WrappedResponses.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai_async.WrappedBetaCompletions.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai_async.WrappedCompletions.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai_async.WrappedCompletions.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai_async.WrappedEmbeddings.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai_async.WrappedResponses.create(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) +method posthog.ai.openai.openai_async.WrappedResponses.parse(posthog_distinct_id: Optional[str] = None, posthog_trace_id: Optional[str] = None, posthog_properties: Optional[Dict[str, Any]] = None, posthog_privacy_mode: bool = False, posthog_groups: Optional[Dict[str, Any]] = None, posthog_provider_override: Optional[str] = None, posthog_options: Optional[Dict[str, Any]] = None, **kwargs: Any) method posthog.ai.openai_agents.processor.PostHogTracingProcessor.force_flush() -> None method posthog.ai.openai_agents.processor.PostHogTracingProcessor.on_span_end(span: Span[Any]) -> None method posthog.ai.openai_agents.processor.PostHogTracingProcessor.on_span_start(span: Span[Any]) -> None @@ -1820,24 +1821,27 @@ method posthog.ai.prompts.Prompts.get(name: str, *, with_metadata: Optional[bool method posthog.ai.prompts.Prompts.get_all(*, label: Optional[str] = None) -> Dict[str, PromptResult] method posthog.ai.stream.AsyncStreamWrapper.aclose() -> None method posthog.ai.stream.AsyncStreamWrapper.close() -> None -method posthog.async_client.AsyncClient.alias(previous_id: ID_TYPES, distinct_id: Optional[str], timestamp: Optional[Union[datetime, str]] = None, uuid: Optional[str] = None, disable_geoip: Optional[bool] = None) -> Optional[str] +method posthog.async_client.AsyncClient.alias(previous_id: ID_TYPES, distinct_id: Optional[str], timestamp: Optional[Union[datetime, str]] = None, uuid: Optional[str] = None, disable_geoip: Optional[bool] = None, options: Optional[Dict[str, Any]] = None) -> Optional[str] method posthog.async_client.AsyncClient.capture(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] -method posthog.async_client.AsyncClient.capture_exception(exception: Optional[ExceptionArg] = None, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] +method posthog.async_client.AsyncClient.capture_ai(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] +method posthog.async_client.AsyncClient.capture_ai_immediate(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] +method posthog.async_client.AsyncClient.capture_exception(exception: Optional[ExceptionArg] = None, *, level: Optional[str] = None, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] method posthog.async_client.AsyncClient.capture_immediate(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] method posthog.async_client.AsyncClient.evaluate_flags(distinct_id: Optional[ID_TYPES] = None, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, disable_geoip: Optional[bool] = None, flag_keys: Optional[list[str]] = None, device_id: Optional[str] = None) -> FeatureFlagEvaluations method posthog.async_client.AsyncClient.flush(timeout_seconds: Optional[float] = 10) -> None method posthog.async_client.AsyncClient.get_remote_config_payload(key: str) -> Optional[Any] -method posthog.async_client.AsyncClient.group_identify(group_type: str, group_key: str, properties: Optional[Dict[str, Any]] = None, timestamp: Optional[Union[datetime, str]] = None, uuid: Optional[Union[str, UUID]] = None, disable_geoip: Optional[bool] = None, distinct_id: Optional[ID_TYPES] = None) -> Optional[str] +method posthog.async_client.AsyncClient.group_identify(group_type: str, group_key: str, properties: Optional[Dict[str, Any]] = None, timestamp: Optional[Union[datetime, str]] = None, uuid: Optional[Union[str, UUID]] = None, disable_geoip: Optional[bool] = None, distinct_id: Optional[ID_TYPES] = None, options: Optional[Dict[str, Any]] = None) -> Optional[str] method posthog.async_client.AsyncClient.join() -> None method posthog.async_client.AsyncClient.set(**kwargs: Unpack[OptionalSetArgs]) -> Optional[str] method posthog.async_client.AsyncClient.set_once(**kwargs: Unpack[OptionalSetArgs]) -> Optional[str] method posthog.async_client.AsyncClient.shutdown() -> None method posthog.bucketed_rate_limiter.BucketedRateLimiter.consume_rate_limit(key: Hashable) -> bool method posthog.bucketed_rate_limiter.BucketedRateLimiter.stop() -> None -method posthog.client.Client.alias(previous_id: ID_TYPES, distinct_id: Optional[str], timestamp: Optional[Union[datetime, str]] = None, uuid: Optional[str] = None, disable_geoip: Optional[bool] = None) -> Optional[str] +method posthog.capture_send.CaptureError.verdict_summary() -> str +method posthog.client.Client.alias(previous_id: ID_TYPES, distinct_id: Optional[str], timestamp: Optional[Union[datetime, str]] = None, uuid: Optional[str] = None, disable_geoip: Optional[bool] = None, options: Optional[Dict[str, Any]] = None) -> Optional[str] method posthog.client.Client.capture(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] method posthog.client.Client.capture_ai(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] -method posthog.client.Client.capture_exception(exception: Optional[ExceptionArg], **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] +method posthog.client.Client.capture_exception(exception: Optional[ExceptionArg], *, level: Optional[str] = None, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] method posthog.client.Client.evaluate_flags(distinct_id: Optional[ID_TYPES] = None, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys: Optional[List[str]] = None, device_id: Optional[str] = None) -> FeatureFlagEvaluations method posthog.client.Client.feature_enabled(key: str, distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[bool] method posthog.client.Client.feature_flag_definitions() @@ -1845,6 +1849,7 @@ method posthog.client.Client.flush(timeout_seconds: Optional[float] = 10) -> Non method posthog.client.Client.get_active_span() -> Optional[Span] method posthog.client.Client.get_all_flags(distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> Optional[dict[str, Union[bool, str]]] method posthog.client.Client.get_all_flags_and_payloads(distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> FlagsAndPayloads +method posthog.client.Client.get_context_options() -> Dict[str, Any] method posthog.client.Client.get_feature_flag(key: str, distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[FlagValue] method posthog.client.Client.get_feature_flag_evaluation_runtime(key: str) -> Optional[FeatureFlagEvaluationRuntime] method posthog.client.Client.get_feature_flag_keys_by_evaluation_runtime(evaluation_runtime: Union[FeatureFlagEvaluationRuntime, str]) -> list[str] @@ -1856,7 +1861,7 @@ method posthog.client.Client.get_feature_variants(distinct_id: ID_TYPES, groups: method posthog.client.Client.get_flags_decision(distinct_id: Optional[ID_TYPES] = None, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> FlagsResponse method posthog.client.Client.get_remote_config_payload(key: str) method posthog.client.Client.get_tags() -> Dict[str, Any] -method posthog.client.Client.group_identify(group_type: str, group_key: str, properties: Optional[Dict[str, Any]] = None, timestamp: Optional[Union[datetime, str]] = None, uuid: Optional[Union[str, UUID]] = None, disable_geoip: Optional[bool] = None, distinct_id: Optional[ID_TYPES] = None) -> Optional[str] +method posthog.client.Client.group_identify(group_type: str, group_key: str, properties: Optional[Dict[str, Any]] = None, timestamp: Optional[Union[datetime, str]] = None, uuid: Optional[Union[str, UUID]] = None, disable_geoip: Optional[bool] = None, distinct_id: Optional[ID_TYPES] = None, options: Optional[Dict[str, Any]] = None) -> Optional[str] method posthog.client.Client.identify_context(distinct_id: str) -> None method posthog.client.Client.join() -> None method posthog.client.Client.load_feature_flags() @@ -1864,6 +1869,7 @@ method posthog.client.Client.new_context(fresh=False, capture_exceptions: Option method posthog.client.Client.scoped(fresh=False, capture_exceptions: Optional[bool] = None) method posthog.client.Client.set(**kwargs: Unpack[OptionalSetArgs]) -> Optional[str] method posthog.client.Client.set_context_device_id(device_id: str) -> None +method posthog.client.Client.set_context_option(key: str, value: Any) -> None method posthog.client.Client.set_context_session(session_id: str) -> None method posthog.client.Client.set_once(**kwargs: Unpack[OptionalSetArgs]) -> Optional[str] method posthog.client.Client.shutdown() -> None @@ -1874,7 +1880,9 @@ method posthog.consumer.Consumer.pause() method posthog.consumer.Consumer.request(batch) method posthog.consumer.Consumer.run() method posthog.consumer.Consumer.upload() +method posthog.contexts.ContextScope.add_option(key: str, value: Any) method posthog.contexts.ContextScope.add_tag(key: str, value: Any) +method posthog.contexts.ContextScope.collect_options() -> Dict[str, Any] method posthog.contexts.ContextScope.collect_tags() -> Dict[str, Any] method posthog.contexts.ContextScope.get_capture_exception_code_variables() -> Optional[bool] method posthog.contexts.ContextScope.get_code_variables_detect_secrets() -> Optional[bool] @@ -1931,14 +1939,14 @@ method posthog.integrations.django.PosthogContextMiddleware.extract_tags(request method posthog.integrations.django.PosthogContextMiddleware.process_exception(request, exception) method posthog.integrations.flask.PosthogFlaskIntegration.init_app(app: Flask) -> None method posthog.integrations.otel.PostHogContextSpanProcessor.on_start(span: Span, parent_context: Optional[Context] = None) -> None -method posthog.mcp.McpAnalytics.capture(event: str, properties: Optional[dict] = None) -> None +method posthog.mcp.McpAnalytics.capture(event: str, properties: Optional[dict] = None, *, event_options: Optional[Dict[str, Any]] = None) -> None method posthog.mcp.McpAnalytics.flush() -> None method posthog.mcp.posthog_mcp.PostHogMCP.capture(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] -method posthog.mcp.posthog_mcp.PostHogMCP.capture_feedback(*, report: FeedbackReport, llm_model: Optional[str] = None, llm_model_source: Optional[MCPAnalyticsModelSource] = None, protocol_version: Optional[str] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, conversation_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, timestamp: Optional[datetime] = None) -> None -method posthog.mcp.posthog_mcp.PostHogMCP.capture_initialize(*, client_name: Optional[str] = None, client_version: Optional[str] = None, protocol_version: Optional[str] = None, parameters: Any = None, response: Any = None, duration_ms: Optional[float] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, timestamp: Optional[datetime] = None) -> None -method posthog.mcp.posthog_mcp.PostHogMCP.capture_missing_capability(*, context: Optional[str] = None, llm_model: Optional[str] = None, llm_model_source: Optional[MCPAnalyticsModelSource] = None, parameters: Any = None, protocol_version: Optional[str] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, conversation_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, timestamp: Optional[datetime] = None) -> None -method posthog.mcp.posthog_mcp.PostHogMCP.capture_tool_call(tool_name: str, *, intent: Optional[str] = None, intent_source: Optional[str] = None, parameters: Any = None, response: Any = None, duration_ms: Optional[float] = None, is_error: bool = False, error: Any = None, error_type: Optional[str] = None, category: Optional[str] = None, tool_description: Optional[str] = None, llm_model: Optional[str] = None, llm_model_source: Optional[MCPAnalyticsModelSource] = None, protocol_version: Optional[str] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, conversation_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, timestamp: Optional[datetime] = None) -> None -method posthog.mcp.posthog_mcp.PostHogMCP.capture_tools_list(*, tool_names: Optional[List[str]] = None, parameters: Any = None, response: Any = None, duration_ms: Optional[float] = None, is_error: bool = False, error: Any = None, error_type: Optional[str] = None, protocol_version: Optional[str] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, timestamp: Optional[datetime] = None) -> None +method posthog.mcp.posthog_mcp.PostHogMCP.capture_feedback(*, report: FeedbackReport, llm_model: Optional[str] = None, llm_model_source: Optional[MCPAnalyticsModelSource] = None, protocol_version: Optional[str] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, conversation_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None) -> None +method posthog.mcp.posthog_mcp.PostHogMCP.capture_initialize(*, client_name: Optional[str] = None, client_version: Optional[str] = None, protocol_version: Optional[str] = None, parameters: Any = None, response: Any = None, duration_ms: Optional[float] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None) -> None +method posthog.mcp.posthog_mcp.PostHogMCP.capture_missing_capability(*, context: Optional[str] = None, llm_model: Optional[str] = None, llm_model_source: Optional[MCPAnalyticsModelSource] = None, parameters: Any = None, protocol_version: Optional[str] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, conversation_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None) -> None +method posthog.mcp.posthog_mcp.PostHogMCP.capture_tool_call(tool_name: str, *, intent: Optional[str] = None, intent_source: Optional[str] = None, parameters: Any = None, response: Any = None, duration_ms: Optional[float] = None, is_error: bool = False, error: Any = None, error_type: Optional[str] = None, category: Optional[str] = None, tool_description: Optional[str] = None, llm_model: Optional[str] = None, llm_model_source: Optional[MCPAnalyticsModelSource] = None, protocol_version: Optional[str] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, conversation_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None) -> None +method posthog.mcp.posthog_mcp.PostHogMCP.capture_tools_list(*, tool_names: Optional[List[str]] = None, parameters: Any = None, response: Any = None, duration_ms: Optional[float] = None, is_error: bool = False, error: Any = None, error_type: Optional[str] = None, protocol_version: Optional[str] = None, distinct_id: Optional[str] = None, session_id: Optional[str] = None, client_user_agent: Optional[str] = None, vendor_client: Optional[str] = None, set_properties: Optional[JsonRecord] = None, groups: Optional[Dict[str, str]] = None, properties: Optional[JsonRecord] = None, event_options: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime] = None) -> None method posthog.mcp.posthog_mcp.PostHogMCP.flush(timeout_seconds: Optional[float] = 10) -> None method posthog.mcp.posthog_mcp.PostHogMCP.prepare_tool_call(name: str, args: Optional[JsonRecord] = None, *, request_meta: Optional[JsonRecord] = None, original_tool: Any = None, session_id: Optional[str] = None) -> PreparedToolCall method posthog.mcp.posthog_mcp.PostHogMCP.prepare_tool_list(tools: List[Any], context: Union[bool, MCPAnalyticsContextOptions] = True, report_missing: bool = False, collect_feedback: bool = False) -> List[Any] @@ -2028,8 +2036,8 @@ module posthog.args module posthog.async_client module posthog.bucketed_rate_limiter module posthog.capture_compression -module posthog.capture_mode -module posthog.capture_v1 +module posthog.capture_event +module posthog.capture_send module posthog.client module posthog.consumer module posthog.contexts diff --git a/sdk_compliance_adapter/CONTRIBUTING.md b/sdk_compliance_adapter/CONTRIBUTING.md index 22b26b50a..e98cd7497 100644 --- a/sdk_compliance_adapter/CONTRIBUTING.md +++ b/sdk_compliance_adapter/CONTRIBUTING.md @@ -4,12 +4,12 @@ This package contains the PostHog Python SDK compliance adapter used with the Po ## Running tests -Tests run automatically in CI via GitHub Actions against harness **1.31.1**, for both capture protocols. Both jobs opt into the local-evaluation suite and fail on compliance regressions. +Tests run automatically in CI via GitHub Actions against harness **1.26.0**. The compliance job runs once for each capture compression (gzip, deflate and zstd). Each run opts into the local-evaluation suite and fails on compliance regressions. Run adapter protocol tests from the repository root in an activated virtual environment: ```bash -python -m pip install -e . -r sdk_compliance_adapter/requirements.txt pytest pytest-timeout pytest-asyncio +python -m pip install -e ".[zstd]" -r sdk_compliance_adapter/requirements.txt pytest pytest-timeout pytest-asyncio python -m pytest sdk_compliance_adapter/test_adapter.py --timeout=30 ``` @@ -44,7 +44,7 @@ docker run -d --name sdk-adapter --network test-network -p 8080:8080 posthog-pyt docker run --rm \ --name test-harness \ --network test-network \ - ghcr.io/posthog/sdk-test-harness:1.31.1 \ + ghcr.io/posthog/sdk-test-harness:1.26.0 \ run --adapter-url http://sdk-adapter:8080 --mock-url http://test-harness:8081 # Cleanup diff --git a/sdk_compliance_adapter/Dockerfile b/sdk_compliance_adapter/Dockerfile index c347f3266..bfc691dd3 100644 --- a/sdk_compliance_adapter/Dockerfile +++ b/sdk_compliance_adapter/Dockerfile @@ -6,8 +6,8 @@ WORKDIR /app COPY posthog/ /app/sdk/posthog/ COPY setup.py pyproject.toml README.md LICENSE /app/sdk/ -# Install the SDK from source -RUN cd /app/sdk && pip install --no-cache-dir -e . +# Install the SDK from source, with zstd for the zstd compliance job +RUN cd /app/sdk && pip install --no-cache-dir -e ".[zstd]" # Install adapter dependencies RUN pip install --no-cache-dir flask python-dateutil diff --git a/sdk_compliance_adapter/Dockerfile.v1 b/sdk_compliance_adapter/Dockerfile.v1 deleted file mode 100644 index 6891837a5..000000000 --- a/sdk_compliance_adapter/Dockerfile.v1 +++ /dev/null @@ -1,25 +0,0 @@ -FROM python:3.12-slim - -WORKDIR /app - -# Copy the SDK source code -COPY posthog/ /app/sdk/posthog/ -COPY setup.py pyproject.toml README.md LICENSE /app/sdk/ - -# Install the SDK from source -RUN cd /app/sdk && pip install --no-cache-dir -e . - -# Install adapter dependencies -RUN pip install --no-cache-dir flask python-dateutil - -# Copy adapter code -COPY sdk_compliance_adapter/adapter.py /app/adapter.py - -# Select the capture-v1 protocol; same adapter code, different runtime mode. -ENV CAPTURE_MODE=v1 - -# Expose port 8080 -EXPOSE 8080 - -# Run the adapter -CMD ["python", "/app/adapter.py"] diff --git a/sdk_compliance_adapter/README.md b/sdk_compliance_adapter/README.md index b35a0b1f7..703f5873a 100644 --- a/sdk_compliance_adapter/README.md +++ b/sdk_compliance_adapter/README.md @@ -31,7 +31,7 @@ The adapter implements the standard SDK adapter interface defined in the [test h ### Key Implementation Details -**Request Tracking**: The adapter monkey-patches `batch_post` to track all HTTP requests made by the SDK, including retries. +**Request Tracking**: The adapter monkey-patches the capture v1 `_post_v1` to track all HTTP requests made by the SDK, including retries. **State Management**: Thread-safe state tracking for events captured vs sent, retry attempts, and errors. @@ -39,8 +39,8 @@ The adapter implements the standard SDK adapter interface defined in the [test h ### Local feature flag evaluation -Both capture adapters advertise `feature_flags_local_evaluation_v1` for harness -**1.1.1**. The capability versions the adapter protocol and tests both legacy and +The adapter advertises `feature_flags_local_evaluation_v1` for harness +**1.25.0**. The capability versions the adapter protocol and tests both legacy and explicit property matching; it does not change the SDK's default matching mode. - `/init` maps optional `personal_api_key` to the SDK's `secret_key`. Ordinary diff --git a/sdk_compliance_adapter/adapter.py b/sdk_compliance_adapter/adapter.py index 4dd0c25b3..18d36976c 100644 --- a/sdk_compliance_adapter/adapter.py +++ b/sdk_compliance_adapter/adapter.py @@ -5,6 +5,7 @@ It wraps the posthog-python SDK and exposes a REST API for the test harness to exercise. """ +import json import logging import os import threading @@ -15,9 +16,9 @@ from posthog import Client from posthog.capture_compression import CaptureCompression -from posthog.capture_v1 import _post_v1 as original_post_v1 -from posthog.request import EVENTS_ENDPOINT, USER_AGENT -from posthog.request import batch_post as original_batch_post +from posthog.capture_send import _CAPTURE_V1_PATH +from posthog.capture_send import _post_v1 as original_post_v1 +from posthog.request import USER_AGENT from posthog.version import VERSION # Configure logging @@ -28,15 +29,18 @@ app = Flask(__name__) -# Selects which capture protocol this adapter process speaks. Baked at build -# time via the CAPTURE_MODE env var ("v1" => capture-v1, anything else => legacy -# v0), mirroring the v0/v1 Dockerfile split. One process speaks one mode and -# advertises it via /health capabilities. -CAPTURE_MODE = os.environ.get("CAPTURE_MODE", "") +# The harness has one enable_compression flag but a test per codec, so each +# adapter instance takes its codec from COMPRESSION and advertises only that +# codec's encoding_ capability. The SDK has no brotli support. +COMPRESSION_CODECS = { + "gzip": CaptureCompression.GZIP, + "deflate": CaptureCompression.DEFLATE, + "zstd": CaptureCompression.ZSTD, +} -def is_v1() -> bool: - return CAPTURE_MODE == "v1" +def compression_name() -> str: + return os.environ.get("COMPRESSION") or "gzip" class RequestInfo: @@ -80,7 +84,8 @@ def __init__(self): self.client: Optional[Client] = None self.remote_client: Client | None = None self.reload_thread: threading.Thread | None = None - self.retry_attempts: Dict[str, int] = {} # Track retry attempts by batch ID + self.reported_drops: List[Dict[str, Any]] = [] + self.log_lines: List[str] = [] def reset(self): """Reset all state""" @@ -99,14 +104,16 @@ def reset(self): except Exception as e: logger.warning(f"Error shutting down client: {e}") + # Cleared after shutdown, which can still report drops and log lines for the old client. with self.lock: + self.reported_drops = [] + self.log_lines = [] self.pending_events = 0 self.total_events_captured = 0 self.total_events_sent = 0 self.total_retries = 0 self.last_error = None self.requests_made = [] - self.retry_attempts = {} def increment_captured(self): """Increment total events captured""" @@ -114,37 +121,6 @@ def increment_captured(self): self.total_events_captured += 1 self.pending_events += 1 - def record_request(self, status_code: int, batch: List[Dict], batch_id: str): - """Record an HTTP request made by the SDK""" - with self.lock: - # Determine retry attempt for this batch - retry_attempt = self.retry_attempts.get(batch_id, 0) - - # Extract UUIDs from batch - uuid_list = [event.get("uuid", "") for event in batch] - - request_info = RequestInfo( - timestamp_ms=int(time.time() * 1000), - status_code=status_code, - retry_attempt=retry_attempt, - event_count=len(batch), - uuid_list=uuid_list, - ) - self.requests_made.append(request_info) - - # Update counters - if status_code == 200: - # Success - clear pending events - self.total_events_sent += len(batch) - self.pending_events = max(0, self.pending_events - len(batch)) - # Remove batch from retry tracking - self.retry_attempts.pop(batch_id, None) - else: - # Failure - increment retry count - self.retry_attempts[batch_id] = retry_attempt + 1 - if retry_attempt > 0: - self.total_retries += 1 - def record_request_v1( self, status_code: int, batch: List[Dict], attempt: int, terminal_count: int ): @@ -187,45 +163,75 @@ def get_state(self) -> Dict[str, Any]: "total_retries": self.total_retries, "last_error": self.last_error, "requests_made": [r.to_dict() for r in self.requests_made], + "reported_drops": list(self.reported_drops), + "log_lines": list(self.log_lines), } + def record_drops(self, error: Exception, batch: List[Dict[str, Any]]) -> None: + """on_error hook: record each event capture dropped, by uuid.""" + # A duplicate uuid has several names in batch order; capture keeps the first copy. + names: Dict[Optional[str], List[Optional[str]]] = {} + for event in batch or []: + names.setdefault(event.get("uuid"), []).append(event.get("event")) + duplicates_seen: Dict[str, int] = {} + with self.lock: + for uuid, details in getattr(error, "drops", []): + copies = names.get(uuid, []) + index = 0 + if details == "duplicate_event_uuid": + index = duplicates_seen.get(uuid, 0) + 1 + duplicates_seen[uuid] = index + name = copies[min(index, len(copies) - 1)] if copies else None + self.reported_drops.append( + {"uuid": uuid, "event": name, "details": details} + ) + + def record_log(self, line: str) -> None: + with self.lock: + self.log_lines.append(line) + # Global state state = SDKState() -def create_batch_id(batch: List[Dict]) -> str: - """Create a unique ID for a batch based on UUIDs""" - uuids = sorted([event.get("uuid", "") for event in batch]) - return "-".join(uuids[:3]) # Use first 3 UUIDs as batch ID +class _StateLogHandler(logging.Handler): + def emit(self, record: logging.LogRecord) -> None: + state.record_log(self.format(record)) -def patched_batch_post( - api_key: str, - host: Optional[str] = None, - gzip: bool = False, - timeout: float = 15, - path: str = EVENTS_ENDPOINT, - **kwargs, -): - """Patched version of batch_post that tracks requests""" - batch = kwargs.get("batch", []) - batch_id = create_batch_id(batch) +# The SDK logs under "posthog"; /state returns those lines (log_capture). +_sdk_logger = logging.getLogger("posthog") +_sdk_logger.addHandler(_StateLogHandler()) +_sdk_logger.setLevel(logging.DEBUG) - try: - # Call original batch_post - response = original_batch_post(api_key, host, gzip, timeout, path, **kwargs) - # Record successful request - state.record_request(200, batch, batch_id) - return response - except Exception as e: - # Record failed request - status_code = ( - getattr(e, "status_code", 500) if hasattr(e, "status_code") else 500 +_PADDING_KEY = "$test_padding" + + +def _padded_properties( + properties: Optional[Dict[str, Any]], size: int, marker: str +) -> Dict[str, Any]: + """Add one ASCII padding property so the properties' compact JSON is exactly ``size`` bytes.""" + padded = {**(properties or {}), _PADDING_KEY: ""} + fill = size - len( + json.dumps(padded, separators=(",", ":"), ensure_ascii=False).encode("utf-8") + ) + # The marker's bytes as written in JSON, escapes included, without its quotes. + marker_bytes = len(json.dumps(marker, ensure_ascii=False).encode("utf-8")) - 2 + if fill < marker_bytes: + raise ValueError( + f"pad_properties_to_bytes {size} is smaller than the properties" ) - state.record_request(status_code, batch, batch_id) - state.record_error(str(e)) - raise + padded[_PADDING_KEY] = marker + "x" * (fill - marker_bytes) + return padded + + +def _before_send(set_properties: Dict[str, Any]): + def hook(event: Dict[str, Any]) -> Dict[str, Any]: + event.setdefault("properties", {}).update(set_properties) + return event + + return hook def patched_post_v1( @@ -239,11 +245,12 @@ def patched_post_v1( timeout: float = 15, sdk_info: str = USER_AGENT, session: Any = None, + path: str = _CAPTURE_V1_PATH, ): """Patched version of _post_v1 that records requests for /state assertions. - Mirrors the legacy `patched_batch_post`, but reads the retry attempt from the - call (1-based) and counts only terminal per-event results as sent. + Reads the retry attempt from the call (1-based) and counts only terminal + per-event results as sent. """ batch = batch_body.get("batch", []) try: @@ -257,6 +264,7 @@ def patched_post_v1( timeout=timeout, sdk_info=sdk_info, session=session, + path=path, ) except Exception as e: status_code = getattr(e, "status", 0) @@ -284,37 +292,37 @@ def patched_post_v1( return response -# Monkey-patch the batch_post function -import posthog.request # noqa: E402 - -posthog.request.batch_post = patched_batch_post - -# Also patch in consumer module -import posthog.consumer # noqa: E402 - -posthog.consumer.batch_post = patched_batch_post - # Patch the capture-v1 submitter. `_send_v1_batch` resolves `_post_v1` as a module # global at call time, so patching it here covers both the async consumer and the # sync client paths. -import posthog.capture_v1 # noqa: E402 +import posthog.capture_send # noqa: E402 -posthog.capture_v1._post_v1 = patched_post_v1 +posthog.capture_send._post_v1 = patched_post_v1 @app.route("/health", methods=["GET"]) def health(): """Health check endpoint""" - capabilities = ( - ["capture_v1", "capture_ai_v0", "encoding_gzip"] - if is_v1() - else ["capture_v0", "capture_ai_v0", "encoding_gzip"] - ) - capabilities.append("feature_flags_local_evaluation_v1") - # Remote /flags requests send ?v=4 and read the v4 flag record. - capabilities.append("flags_response_v4") - # The legacy payload accessor is exposed on /get_feature_flag_payload. - capabilities.append("feature_flag_payloads") + capabilities = [ + "capture_v1", + "capture_ai_v1", + "event_options", + "event_uuid_override", + "bounded_retries", + "disable_geoip", + "historical_migration", + "reported_drops", + "log_capture", + "generated_payloads", + "property_layers", + "fail_open", + "encoding_" + compression_name(), + "feature_flags_local_evaluation_v1", + # Remote /flags requests send ?v=4 and read the v4 flag record. + "flags_response_v4", + # The legacy payload accessor is exposed on /get_feature_flag_payload. + "feature_flag_payloads", + ] return jsonify( { "sdk_name": "posthog-python", @@ -347,7 +355,8 @@ def init(): disable_geoip = data.get("disable_geoip", False) historical_migration = data.get("historical_migration", False) - if not api_key: + # An empty or personal key must reach the SDK, which disables itself (fail_open). + if api_key is None: return jsonify({"error": "api_key is required"}), 400 if not host: return jsonify({"error": "host is required"}), 400 @@ -355,9 +364,11 @@ def init(): # Convert flush_interval from ms to seconds flush_interval = flush_interval_ms / 1000.0 - # One adapter process speaks one capture protocol, selected by CAPTURE_MODE. - capture_mode = "v1" if is_v1() else "v0" - + compression = ( + COMPRESSION_CODECS[compression_name()] + if enable_compression + else CaptureCompression.NONE + ) # Explicit reloads exercise the real loader without background polling # racing the harness's per-test definition snapshots. client_options = { @@ -365,14 +376,21 @@ def init(): "host": host, "flush_at": flush_at, "flush_interval": flush_interval, - "gzip": enable_compression, + "capture_compression": compression, + "capture_ai_compression": compression, "max_retries": max_retries, "debug": False, "disable_geoip": disable_geoip, "historical_migration": historical_migration, - "capture_mode": capture_mode, "enable_local_evaluation": False, + "on_error": state.record_drops, + "super_properties": data.get("super_properties"), } + before_send = data.get("before_send") + if before_send: + client_options["before_send"] = _before_send( + before_send.get("set_properties", {}) + ) personal_api_key = data.get("personal_api_key") client = Client(**client_options, secret_key=personal_api_key) state.client = client @@ -383,10 +401,10 @@ def init(): state.remote_client = Client(**client_options) logger.info( - f"Initialized SDK with api_key={api_key[:10]}..., host={host}, " + f"Initialized SDK with api_key={api_key[:4]}..., host={host}, " f"flush_at={flush_at}, flush_interval={flush_interval}, " - f"max_retries={max_retries}, gzip={enable_compression}, " - f"capture_mode={capture_mode}, disable_geoip={disable_geoip}, " + f"max_retries={max_retries}, compression={enable_compression}, " + f"disable_geoip={disable_geoip}, " f"historical_migration={historical_migration}" ) @@ -396,57 +414,60 @@ def init(): return jsonify({"error": str(e)}), 500 -@app.route("/capture", methods=["POST"]) -def capture(): - """Capture a single event""" - try: - if not state.client: - return jsonify({"error": "SDK not initialized"}), 400 +def _capture_with(capture_method_name: str): + """Capture one event through the named SDK method. - data = request.json or {} + Options pass through unchanged, and a supplied uuid stays on the wire. The + response carries the uuid the SDK actually sent, which differs from the + supplied one when the SDK canonicalizes or replaces it. + """ + if not state.client: + return jsonify({"error": "SDK not initialized"}), 400 - distinct_id = data.get("distinct_id") - event = data.get("event") - properties = data.get("properties") - timestamp = data.get("timestamp") - options = data.get("options") + data = request.json or {} - if not distinct_id: - return jsonify({"error": "distinct_id is required"}), 400 - if not event: - return jsonify({"error": "event is required"}), 400 - - # Fold capture-v1 options back into the magic `$`-prefixed properties the - # SDK lifts onto the wire `options` object. Renamed keys mirror the SDK's - # sentinel table; unknown keys get a bare `$` prefix. v0 has no wire - # options object, so this only applies in v1 mode. - if options and is_v1(): - properties = dict(properties or {}) - option_to_property = { - "cookieless_mode": "$cookieless_mode", - "disable_skew_correction": "$ignore_sent_at", - "process_person_profile": "$process_person_profile", - "product_tour_id": "$product_tour_id", - } - for key, value in options.items(): - properties[option_to_property.get(key, "$" + key)] = value + distinct_id = data.get("distinct_id") + event = data.get("event") + timestamp = data.get("timestamp") - # Capture event - kwargs = {"distinct_id": distinct_id, "properties": properties} - if timestamp: - # Parse ISO8601 timestamp - from dateutil.parser import parse + if not distinct_id: + return jsonify({"error": "distinct_id is required"}), 400 + if not event: + return jsonify({"error": "event is required"}), 400 - kwargs["timestamp"] = parse(timestamp) + properties = data.get("properties") + if data.get("pad_properties_to_bytes") is not None: + properties = _padded_properties( + properties, data["pad_properties_to_bytes"], data.get("marker") or "" + ) + kwargs = { + "distinct_id": distinct_id, + "properties": properties, + "options": data.get("options"), + } + if timestamp: + # Parse ISO8601 timestamp + from dateutil.parser import parse + + kwargs["timestamp"] = parse(timestamp) + if data.get("uuid"): + kwargs["uuid"] = data["uuid"] + + uuid = getattr(state.client, capture_method_name)(event, **kwargs) - uuid = state.client.capture(event, **kwargs) + # Track that we captured an event + state.increment_captured() - # Track that we captured an event - state.increment_captured() + logger.info(f"Captured event: {event} for {distinct_id}, uuid={uuid}") - logger.info(f"Captured event: {event} for {distinct_id}, uuid={uuid}") + return jsonify({"success": True, "uuid": uuid}) - return jsonify({"success": True, "uuid": uuid}) + +@app.route("/capture", methods=["POST"]) +def capture(): + """Capture a single event""" + try: + return _capture_with("capture") except Exception as e: logger.exception("Error capturing event") state.record_error(str(e)) @@ -457,50 +478,7 @@ def capture(): def capture_ai(): """Capture a single AI event on the dedicated AI capture endpoint""" try: - if not state.client: - return jsonify({"error": "SDK not initialized"}), 400 - - data = request.json or {} - - distinct_id = data.get("distinct_id") - event = data.get("event") - properties = data.get("properties") - timestamp = data.get("timestamp") - options = data.get("options") - supplied_uuid = data.get("uuid") - - if not distinct_id: - return jsonify({"error": "distinct_id is required"}), 400 - if not event: - return jsonify({"error": "event is required"}), 400 - - if options and is_v1(): - properties = dict(properties or {}) - option_to_property = { - "cookieless_mode": "$cookieless_mode", - "disable_skew_correction": "$ignore_sent_at", - "process_person_profile": "$process_person_profile", - "product_tour_id": "$product_tour_id", - } - for key, value in options.items(): - properties[option_to_property.get(key, "$" + key)] = value - - kwargs = {"distinct_id": distinct_id, "properties": properties} - if timestamp: - from dateutil.parser import parse - - kwargs["timestamp"] = parse(timestamp) - # Unlike /capture, forward a supplied uuid so it's echoed back to the caller. - if supplied_uuid: - kwargs["uuid"] = supplied_uuid - - uuid = state.client.capture_ai(event, **kwargs) - - state.increment_captured() - - logger.info(f"Captured AI event: {event} for {distinct_id}, uuid={uuid}") - - return jsonify({"success": True, "uuid": uuid}) + return _capture_with("capture_ai") except Exception as e: logger.exception("Error capturing AI event") state.record_error(str(e)) @@ -762,7 +740,14 @@ def reset(): def main(): """Main entry point""" port = int(os.environ.get("PORT", 8080)) - logger.info(f"Starting SDK Test Adapter on port {port}") + if compression_name() not in COMPRESSION_CODECS: + raise SystemExit( + f"unsupported COMPRESSION {compression_name()!r}: " + f"want one of {', '.join(COMPRESSION_CODECS)}" + ) + logger.info( + f"Starting SDK Test Adapter on port {port} (compression={compression_name()})" + ) app.run(host="0.0.0.0", port=port, debug=False) diff --git a/sdk_compliance_adapter/docker-compose.yml b/sdk_compliance_adapter/docker-compose.yml index ead39d536..23a8bd6cc 100644 --- a/sdk_compliance_adapter/docker-compose.yml +++ b/sdk_compliance_adapter/docker-compose.yml @@ -1,29 +1,22 @@ version: "3.8" services: - # PostHog Python SDK adapter (capture v0) + # PostHog Python SDK adapter sdk-adapter: build: context: .. dockerfile: sdk_compliance_adapter/Dockerfile + environment: + # One of gzip, deflate or zstd; selects the encoding_ test. + COMPRESSION: ${COMPRESSION:-gzip} ports: - "8080:8080" networks: - test-network - # PostHog Python SDK adapter (capture v1) - sdk-adapter-v1: - build: - context: .. - dockerfile: sdk_compliance_adapter/Dockerfile.v1 - ports: - - "8082:8080" - networks: - - test-network - # Test harness test-harness: - image: ghcr.io/posthog/sdk-test-harness:1.31.1 + image: ghcr.io/posthog/sdk-test-harness:1.26.0 command: ["run", "--adapter-url", "http://sdk-adapter:8080", "--mock-url", "http://test-harness:8081"] networks: - test-network diff --git a/sdk_compliance_adapter/test_adapter.py b/sdk_compliance_adapter/test_adapter.py index 8867b6ae9..6c12e86ee 100644 --- a/sdk_compliance_adapter/test_adapter.py +++ b/sdk_compliance_adapter/test_adapter.py @@ -8,7 +8,7 @@ import pytest -import posthog.capture_v1 +import posthog.capture_send import posthog.client import posthog.consumer import posthog.request @@ -20,9 +20,7 @@ def adapter(monkeypatch): # Importing the adapter installs transport instrumentation. Restore it after # every test so collecting these tests alongside SDK tests is safe. for module, name in [ - (posthog.request, "batch_post"), - (posthog.consumer, "batch_post"), - (posthog.capture_v1, "_post_v1"), + (posthog.capture_send, "_post_v1"), ]: monkeypatch.setattr(module, name, getattr(module, name)) spec = importlib.util.spec_from_file_location( @@ -79,17 +77,70 @@ def initialize(adapter, **overrides): return adapter.app.test_client() -@pytest.mark.parametrize("mode,capability", [("", "capture_v0"), ("v1", "capture_v1")]) -def test_health_opts_into_local_evaluation_without_losing_capture( - adapter, monkeypatch, mode, capability -): - monkeypatch.setattr(adapter, "CAPTURE_MODE", mode) +@pytest.mark.parametrize( + "env_value,codec", + [(None, "gzip"), ("gzip", "gzip"), ("deflate", "deflate"), ("zstd", "zstd")], +) +def test_health_and_init_use_one_codec(adapter, monkeypatch, env_value, codec): + if env_value is None: + monkeypatch.delenv("COMPRESSION", raising=False) + else: + monkeypatch.setenv("COMPRESSION", env_value) capabilities = adapter.app.test_client().get("/health").json["capabilities"] assert "feature_flags_local_evaluation_v1" in capabilities + assert { + "capture_v1", + "capture_ai_v1", + "event_options", + "event_uuid_override", + "bounded_retries", + "disable_geoip", + "historical_migration", + } <= set(capabilities) assert "flags_response_v4" in capabilities assert "feature_flag_payloads" in capabilities - assert capability in capabilities - assert "capture_ai_v0" in capabilities + assert "capture_v0" not in capabilities + assert "capture_ai_v0" not in capabilities + assert [c for c in capabilities if c.startswith("encoding_")] == [ + f"encoding_{codec}" + ] + + initialize(adapter, enable_compression=True) + assert adapter.state.client.capture_compression.value == codec + assert adapter.state.client.capture_ai_compression.value == codec + + +@pytest.mark.parametrize( + "route,method", [("/capture", "capture"), ("/capture_ai", "capture_ai")] +) +def test_capture_passes_options_and_uuid_unchanged(adapter, monkeypatch, route, method): + client = initialize(adapter, personal_api_key=None) + sent = Mock(return_value="0190a5a8-0000-7000-8000-000000000001") + monkeypatch.setattr(adapter.state.client, method, sent) + options = {"cookieless_mode": "no", "process_person_profile": 0.0, "custom": [1]} + + response = client.post( + route, + json={ + "distinct_id": "user", + "event": "$ai_generation", + "properties": {"$ignore_sent_at": "maybe"}, + "options": options, + "uuid": "0190A5A8-0000-7000-8000-000000000001", + }, + ) + + assert response.json == { + "success": True, + "uuid": "0190a5a8-0000-7000-8000-000000000001", + } + sent.assert_called_once_with( + "$ai_generation", + distinct_id="user", + properties={"$ignore_sent_at": "maybe"}, + options=options, + uuid="0190A5A8-0000-7000-8000-000000000001", + ) def test_init_enables_explicit_definitions_loading_without_polling(adapter): diff --git a/typings/requests/__init__.pyi b/typings/requests/__init__.pyi index 91e583b5e..7504def75 100644 --- a/typings/requests/__init__.pyi +++ b/typings/requests/__init__.pyi @@ -66,6 +66,7 @@ class Session: headers: dict[str, str], timeout: float, stream: bool = ..., + allow_redirects: bool = ..., ) -> Response: ... def get( self, diff --git a/uv.lock b/uv.lock index 04425987e..746417428 100644 --- a/uv.lock +++ b/uv.lock @@ -387,15 +387,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/39/44/a46089266de32a0d809023b6bf31b80a1f26a46954446a7ce695a565cbea/authlib-1.9.1-py2.py3-none-any.whl", hash = "sha256:8b9be8b1e5174dcbf5520e984f1a22dc2edae5b6e40a61d4cedbf86b97e9e69b", size = 266042, upload-time = "2026-10-14T14:17:50.695Z" }, ] -[[package]] -name = "backoff" -version = "2.2.1" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/47/d7/5bbeb12c44d7c4f2fb5b56abce497eb5ed9f34d85701de869acedd602619/backoff-2.2.1.tar.gz", hash = "sha256:03f829f5bb1923180821643f8753b0502c3b682293992485b0eef2807afa5cba", size = 17001, upload-time = "2022-10-05T19:19:32.061Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/df/73/b6e24bd22e6720ca8ee9a85a0c4a2971af8497d8f3193fa05390cbd46e09/backoff-2.2.1-py3-none-any.whl", hash = "sha256:63579f9a0628e06278f7e47b7d7d5b6ce20dc65c5e96a6f3ca99a6adca0396e8", size = 15148, upload-time = "2022-10-05T19:19:30.546Z" }, -] - [[package]] name = "backports-asyncio-runner" version = "1.2.0" @@ -3467,7 +3458,6 @@ name = "posthog" version = "7.91.4" source = { editable = "." } dependencies = [ - { name = "backoff" }, { name = "distro" }, { name = "requests" }, { name = "typing-extensions" }, @@ -3571,7 +3561,6 @@ dev = [ [package.metadata] requires-dist = [ { name = "anthropic", marker = "extra == 'test'", specifier = ">=0.72" }, - { name = "backoff", specifier = ">=1.10.0" }, { name = "celery", marker = "extra == 'test'", specifier = ">=5.3,<6" }, { name = "claude-agent-sdk", marker = "extra == 'test'" }, { name = "coverage", marker = "extra == 'test'" },