Skip to content
Skills Library
Programming · Analysis

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.

Repository
posthog ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

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

  1. Find the source of the delay
  2. Capture the exact work
  3. Compare the smallest useful change
  4. Verify the change
  5. Common mistakes
Original SKILL.md headings · 81 lines, 557 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.