perlsky is a Perl 5 implementation of an AT Protocol Personal Data Server.
1# Performance
2
3This document covers two practical tools for `perlsky` performance work:
4
5- Prometheus metrics for live visibility
6- `script/benchmark-local-appview` for repeatable local endpoint timing
7
8## Benchmark Script
9
10`script/benchmark-local-appview` spins up an ephemeral local `perlsky` daemon, seeds a small repo with posts and a reply chain, then benchmarks the hottest local appview endpoints over real HTTP:
11
12- `app.bsky.actor.getProfile`
13- `app.bsky.feed.getAuthorFeed`
14- `app.bsky.feed.getPostThread`
15
16Example:
17
18```sh
19script/benchmark-local-appview --iterations 75 --warmup 15 --posts 100 --replies 12
20```
21
22JSON output:
23
24```sh
25script/benchmark-local-appview --format json > data/local-appview-benchmark.json
26```
27
28The benchmark is intentionally small and deterministic. It is best for comparing one local appview change against another, not for claiming cluster-scale throughput.
29
30Useful flags:
31
32- `--iterations N`: measured requests per endpoint, default `50`
33- `--warmup N`: unmeasured warmup requests per endpoint, default `10`
34- `--posts N`: number of posts to seed for the author feed, default `50`
35- `--replies N`: length of the reply chain for the thread benchmark, default `8`
36- `--feed-limit N`: `getAuthorFeed` page size, default `25`
37- `--keep-tmp`: keep the temporary benchmark dataset on disk for inspection
38
39The script also prints a metrics excerpt so it is easy to sanity-check whether local appview cache counters moved during the run.
40
41## Recommended Workflow
42
43For repeatable tuning:
44
451. Run the benchmark script before a perf change and save the output.
462. Apply the change.
473. Run the same benchmark again with the same arguments.
484. Compare:
49 - `p50`
50 - `p95`
51 - `max`
52 - derived `req/s`
535. Check `/metrics` to confirm that cache hit/rebuild counters changed the way you expected.
546. If the change looks promising, compare the same Prometheus panels in Grafana after deployment.
55
56## Current Hot Metrics
57
58The most relevant local appview metrics are:
59
60- `perlsky_service_proxy_requests_total`
61- `perlsky_service_proxy_request_duration_seconds`
62- `perlsky_service_proxy_local_post_index_cache_access_total`
63- `perlsky_service_proxy_local_post_index_rebuild_duration_seconds`
64- `perlsky_service_proxy_local_post_index_entries`
65- `perlsky_service_proxy_local_post_resolution_total`
66- `perlsky_service_proxy_profile_record_cache_total`
67- `perlsky_repo_resolution_total`
68
69See [METRICS.md](./METRICS.md) for Prometheus and Grafana queries.