profiling-slow-api-endpoints
/profiling-slow-api-endpoints
Profiles slow PostHog API endpoints when the main cost is in Postgres or Python. Use when a screen, picker, or list is slow; a Django endpoint has high tail latency; a query plan changes with tenant size; or a proposed database fix needs production evidence. Covers APM traces, safe production EXPLAIN, representative measurements, implementation choices, tests, rollout, and post-deploy verification. For ClickHouse or HogQL latency, use `optimizing-clickhouse-and-hogql-queries` instead.
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Profiles slow PostHog API endpoints when the main cost is in Postgres or Python. Use when a screen, picker, or list is slow; a Django endpoint has high tail latency; a query plan changes with tenant size; or a proposed database fix needs production evidence. Covers APM traces, safe production EXPLAIN, representative measurements, implementation choices, tests, rollout, and post-deploy verification. For ClickHouse or HogQL latency, use `optimizing-clickhouse-and-hogql-queries` instead.
Original author description
Profiles slow PostHog API endpoints when the main cost is in Postgres or Python. Use when a screen, picker, or list is slow; a Django endpoint has high tail latency; a query plan changes with tenant size; or a proposed database fix needs production evidence. Covers APM traces, safe production EXPLAIN, representative measurements, implementation choices, tests, rollout, and post-deploy verification. For ClickHouse or HogQL latency, use `optimizing-clickhouse-and-hogql-queries` instead.
How it works
- Find the source of the delay
- Capture the exact work
- Compare the smallest useful change
- Verify the change
- Common mistakes
SKILL.md preview
--- name: profiling-slow-api-endpoints description: > Profiles slow PostHog API endpoints when the main cost is in Postgres or Python. Use when a screen, picker, or list is slow; a Django endpoint has high tail latency; a query plan changes with tenant size; or a proposed database fix needs production evidence. Covers APM traces, safe production EXPLAIN, representative measurements, implementation choices, tests, rollout, and post-deploy verification. For ClickHouse or HogQL latency, use `optimizing-clickhouse-and-hogql-queries` instead. --- # Profiling slow API endpoints Use this skill when a PostHog API request spends most of its time in Postgres or Python. For ClickHouse and HogQL, use [`optimizing-clickhouse-and-hogql-queries`](../optimizing-clickhouse-and-hogql-queries/SKILL.md). Measure the same user action before and after the change. A faster query does not help if the action stays slow. ## Find the source of the delay Record the page action, endpoint, request shape, affected users, request volume, and a latency percentile such as p95. Read slow APM traces with `posthog:query-apm-spans` and the `exploring-apm-traces` skill. The distribution shows how often requests are slow. The traces show where they spend time. - Django ORM and `cursor.execute` spans point to Postgres. - ClickHouse work belongs in the ClickHouse skill. - Time outside database spans can indicate repeated calls, serialization, or excess data loading. Follow the request to the function that creates the work. Do not optimize a view wrapper when another function owns the delay. ## Capture the exact work Get the SQL and parameters from a slow request. Keep its filters, ordering, and page size. Check for repeated queries, count queries, and work that does not block the response. A reduced query can use a different plan. Local data and statistics can also produce a different plan. Use [`querying-production-databases-via-metabase`](../querying-production-databases-via-metabase/SKILL.md) to inspect the production read replica. Start with `EXPLAIN`. Use `EXPLAIN (ANALYZE, BUFFERS)` only when the exact `SELECT` is safe to run. Inspect row estimates, indexes, join types, loops, filters, sorts, and buffer use. ## Compare the smallest useful change Remove work that the response does not need before you change a query or add an index. Compare the original and candidate with the same parameters. Run each more than once, record the cache state, and verify equal results. Measure the tenant-size distribution when plans can change with tenant size. Test both sides of a plan crossover before you select a threshold. One tenant is not enough evidence for a conditional plan. Prefer one plan when it performs well across the measured range. If a size check or cache selects the plan: - keep the check cheaper than the work it avoids - let stale data affect latency, not results - keep the request working when the cache fails - record the selected plan on the request span Use a feature flag when behavior is uncertain or the change needs a staged rollout. Do not use a flag as a substitute for measurements. ## Verify the change Test public behavior at the lowest useful level. Add plan or SQL-shape tests only when the improvement depends on that shape. Test each plan and the failure path when the code selects between plans. Use a representative database for plan and timing comparisons because unit tests cannot prove latency. After deployment, check the same latency measure, request volume, error rate, and database load. Compare recorded plan attributes when more than one plan exists. Remove the change if it does not improve the user action without a regression. ## Common mistakes - Starting with a code theory instead of a slow trace. - Measuring only the mean or one warm query. - Testing SQL that differs from the endpoint SQL. - Selecting a threshold from one tenant. - Moving the first response behind optional work. - Adding an index before checking the current plan. - Declaring success from tests instead of the production measure.
Versions
The database has no other skills named profiling-slow-api-endpoints.
Database snapshot: 13.11.2026 · package version 725b0de6f9fd (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100writing-clickhouse-queries
Guide for writing performant ClickHouse queries in PostHog product code. Use when writing HogQL query runners, adding or reviewing a ClickHouse call site (`sync_execute`, `execute_hogql_query`, a `QueryRunner`) and choosing its `Workload` (ONLINE, OFFLINE, LOGS, ENDPOINTS),… - 100optimizing-clickhouse-and-hogql-queries
Workflow for optimizing ClickHouse and HogQL queries. Use when a HogQL query, query runner, insight, or report is too slow; when a hand-written ClickHouse query (via `sync_execute` or in a migration) is too slow; when ClickHouse times out or hits memory limits; when… - 100fix-slow-endpoint
Diagnose and fix a slow endpoint or request in a Python web app (FastAPI, Flask, Django, Tornado, any ASGI/WSGI framework) using real Profyle/VizTracer traces, then prove the fix by replaying the request and comparing traces. Use when the user says an endpoint, API call, page or… - 95exploring-apm-traces
Investigates distributed application performance using PostHog APM (OpenTelemetry span) data via MCP. Use when the user asks about service traces, slow HTTP/database spans, error spans, error-rate trends or spikes, latency distributions, trace IDs, or span attributes — not AI… - 100exploring-apm-traces
Investigates distributed application performance using PostHog APM (OpenTelemetry span) data via MCP. Use when the user asks about service traces, slow HTTP/database spans, error spans, error-rate trends or spikes, latency distributions, trace IDs, or span attributes — not AI… - 100sql-optimization
Makes a specific slow query fast from planner evidence: Postgres EXPLAIN ANALYZE or Mongo explain(\"executionStats\"), COLLSCAN, N+1, index fit, rewrite, before/after numbers. Use when a query, endpoint or report is slow or DB CPU is high.