:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
fix(aio): map ranked distinct_id to person uuid in expensive-users skill (#117067)
posthog[bot]308f6cca0482
diff --git a/products/ai_observability/skills/analyzing-expensive-users/SKILL.md b/products/ai_observability/skills/analyzing-expensive-users/SKILL.mdindex c29e0ada1eab..8e0314822c30 100644--- a/products/ai_observability/skills/analyzing-expensive-users/SKILL.md+++ b/products/ai_observability/skills/analyzing-expensive-users/SKILL.md@@ -22,7 +22,7 @@ individual traces, also use `exploring-llm-traces`.| Tool | Purpose || ------------------------------- | ------------------------------------------------------------------ || `posthog:execute-sql` | Rank users and compare their metrics against the project baseline |-| `posthog:query-llm-traces-list` | Find high-cost traces for a specific user |+| `posthog:query-llm-traces-list` | Find high-cost traces for a specific user (by person UUID) || `posthog:query-llm-trace` | Read representative traces to explain what actually happened || `posthog:read-data-schema` | Discover custom event or person properties before grouping by them || `posthog:generate-app-url` | Build region- and project-qualified links back to the UI |@@ -63,6 +63,7 @@ SELECTdistinct_id,argMax(email, timestamp) AS email,argMax(name, timestamp) AS name,+ argMax(person_id, timestamp) AS person_uuid,countDistinctIf(ai_trace_id, notEmpty(ai_trace_id)) AS traces,count() AS generations,countIf(notEmpty(ai_error) OR ai_is_error = 'true') AS errors,@@ -76,6 +77,7 @@ FROM (SELECTdistinct_id,timestamp,+ person_id,toString(properties.$ai_trace_id) AS ai_trace_id,toFloat(properties.$ai_total_cost_usd) AS ai_total_cost_usd,toString(properties.$ai_error) AS ai_error,@@ -108,6 +110,10 @@ Never select the raw `person.properties` object or a tuple containing it: itserializes the full property blob into the result and leaks personal data farbeyond a label. If a user has no email or name, fall back to `distinct_id`.+Keep `person_uuid` for each user you plan to explain. Step 5 needs it.+Name it differently from the inner `person_id` column. A bare `person_id` alias+nests `argMax()` inside itself and fails the query.+### 2. Establish the baselineThe top user is only meaningful relative to everyone else. Run a per-user@@ -231,7 +237,8 @@ Useful comparisons:### 5. Find the user's expensive tracesUse SQL for the ranked trace list, then read representative traces with-`posthog:query-llm-trace`.+`posthog:query-llm-trace`. Both steps take a `distinct_id` or a trace ID, so+they do not need a person UUID.```sqlposthog:execute-sql@@ -265,6 +272,45 @@ posthog:query-llm-trace}```+To list the user's traces with `posthog:query-llm-traces-list`, pass the+`person_uuid` from step 1 as `personId`. Do not pass the `distinct_id`.+`personId` accepts only a full person UUID, so a `distinct_id` fails the query.+Preserve the test-account filter used in the SQL ranking, including any filter supplied by the user.+Set `filterTestAccounts` to `true` when the ranking excludes test accounts, and `false` when it includes them.+The example below uses `false` to match the unfiltered SQL ranking shown above.+The list also includes traces from the person's+other distinct IDs, so its totals can differ from the SQL ranking.++```json+posthog:query-llm-traces-list+{+ "personId": "<person_uuid>",+ "dateRange": { "date_from": "-30d" },+ "filterTestAccounts": false+}+```++If you did not keep `person_uuid`, look it up for the selected `distinct_id`:++```sql+posthog:execute-sql+SELECT+ person_id AS person_uuid,+ count() AS generations,+ max(timestamp) AS last_seen+FROM events+WHERE event = '$ai_generation'+ AND timestamp >= now() - INTERVAL 30 DAY+ AND distinct_id = '<distinct_id>'+GROUP BY person_uuid+ORDER BY generations DESC+```++If this returns more than one row, the `distinct_id` maps to more than one+person. Use the row with the most generations and say so in the caveats. If it+returns no row, do not continue with `query-llm-traces-list`. Use the SQL trace+ranking above and open each trace with `posthog:query-llm-trace` instead.+Look for the first concrete pattern that explains the aggregate:- repeated tool calls or retry loops