PostHog Events Debugging

PostHog Events Debugging

When debugging events or persons:

• Use posthog_list_events (tool name may have a suffix if multiple PostHog servers exist) with filters (event, distinctId, personId, after, before) to find relevant data.
• Use posthog_get_person or posthog_list_persons to inspect user profiles and property consistency.
• For data quality, check that expected events exist and have the right properties via posthog_list_events.
• Always specify projectId; call posthog_list_projects first if unknown.
• When reporting issues, include event names, distinct_id or person_id, and sample payloads where helpful.

Step-by-step instructions

1. Resolve projectId: call posthog_list_projects if unknown.
2. For event issues: call posthog_list_events with projectId, event, distinctId/​personId, and after/​before; inspect returned payloads for properties and shape.
3. For person issues: call posthog_get_person or posthog_list_persons with projectId; check properties and linked events.
4. For data quality: call posthog_list_events for expected event names and check presence and key properties; report missing or malformed data.
5. When reporting: include event names, IDs, and (if useful) a sample payload or property list.

Examples of inputs and outputs

• Input: “Did we receive ‘purchase_completed’ for user X?”
  Output: Yes/​no plus count and time range from posthog_list_events; if yes, optionally one sample payload; cite projectId and distinctId/​personId used.

• Input: “What properties does person Y have?”
  Output: List of properties (and values if appropriate) from posthog_get_person; mention if no person found.

Common edge cases

• No events found: Report “no events matching filters” and suggest widening after/​before range or checking distinctId/​event name.
• Person not found: Say so and suggest checking ID or project.
• Unexpected properties: List what you see and note any missing or wrong property names/​types.
• Rate limits: Report and suggest narrowing filters or retrying later.

Tool usage for specific purposes

• posthog_list_events: Use to find events by event name, distinctId, personId, or after/​before; use for “did we get this event?” and payload inspection.
• posthog_get_person / posthog_list_persons: Use to inspect a user’s profile and properties; use for “what does this user have?” and data quality.
• posthog_list_projects: Use when projectId is unknown before running event or person queries.