Penguin Statistics

Penguin Statistics - V3 バックエンド

Go で構築された、再設計版 Penguin Statistics v3 バックエンドです。

データの利用

ドロップデータは公開されています。

• REST API は https://penguin-stats.io/PenguinStats/api/v2/ で利用できます。開発者向けドキュメントと OpenAPI（Swagger 2.0）仕様をご覧ください。

• AI アシスタント（Claude、ChatGPT、Cursor、VS Code、Cherry Studio など）向けの MCP サーバー は https://mcp.penguin-stats.io/mcp で利用できます。Streamable HTTP、認証不要、読み取り専用です。Claude Code では次のようにします。

  claude mcp add --transport http --scope user penguin-stats https://mcp.penguin-stats.io/mcp
  

  その他のアプリでの手順は、英語と中国語で https://mcp.penguin-stats.io/ に掲載されています。

• コーディングエージェント向けの プラグインとスキル です。数値の読み取り、引用、クエリの実行に関するスキルを備えた MCP サーバーです。 https://github.com/penguin-statistics/agent-skills

ドロップデータのライセンスは CC BY-NC 4.0 です。クレジット表記が必要な非営利利用に限られます。 Data: Penguin Statistics (penguin-stats.io), CC BY-NC 4.0 と表記してください。このリポジトリのコードは MIT ライセンスです。

アーキテクチャ

この Go プロジェクトでは、主に次のものを使用しています。

• gofiber/fiber
• uber-go/fx
• uptrace/bun

このプロジェクトは主に RESTful API 設計に従っています。

運用

デッドレターストリーム内のレポートタスク

レポートワーカーは、レポートタスクを処理できない場合（タスクではない場合、またはタスクのステージが存在しない場合）、あるいは30回の配信すべてで失敗した場合に、penguin-reports ストリームから penguin-reports-dead（サブジェクトは REPORT_DEAD.*）へタスクを移動します。30回の配信には、約97分の再試行間隔がかかります。移動のたびにエラーレベルでログが記録されます （reportwkr.malformed、reportwkr.parked、または reportwkr.dead）。コピーには公開時のペイロードがそのまま保持され、次のヘッダーが付与されます。

• Penguin-Original-Subject：公開時のサブジェクト。例：REPORT.SINGLE
• Penguin-Original-Sequence：penguin-reports 内でのシーケンス番号
• Penguin-Deliveries：移動時の配信回数
• Penguin-Last-Error：移動の原因となったエラー

ヘッダーを追加すると最大ペイロードサイズを超えるほど大きなタスクは、ヘッダーなしで移動されます。この場合、REPORT_DEAD.* のサブジェクトが元のサブジェクトを示し、移動はシーケンス番号とエラーとともに reportwkr.dead.bare としてログに記録されます。

ストリーム内のデータは期限切れになりません。nats CLI を使い、原因を修正したら次のようにします。

# list the tasks, with their headers
nats stream view penguin-reports-dead
# show one, by its sequence in penguin-reports-dead
nats stream get penguin-reports-dead 42
# replay it under its original subject: the worker processes it as a new task
nats stream get penguin-reports-dead 42 --json | jq -r .data | base64 -d \
  | nats pub REPORT.SINGLE --force-stdin
# remove it once replayed
nats stream rmm penguin-reports-dead 42 -f

各配信で失敗した後に移動されたタスクは、コミットの結果が不明だった配信によって保存されている可能性があります（たとえば、コミット中に接続が切断された場合など）。再実行する前に、該当するアカウントと時刻の drop_reports を確認してください。

ベンチマーク

レポートコンシューマーの CPU

internal/workers/reportwkr/consumerbench_test.go（ビルドタグ consumerbench）では、レポートコンシューマーを実際のコードパスで実行します。各タスクは専用の JetStream ストリームにパブリッシュされ、取得後、Worker.ingestPreprocess（BenchmarkConsumer/ingest）に渡されます。ここで PostgreSQL に保存し、Redis にリコールキーを設定します。ロギングとトレーシングは本番環境と同じように設定されます。BenchmarkConsumer/process では Worker.process のみを実行します。実行時間とメモリアロケーションに加え、タスクごとのプロセス CPU 時間（cpu-ns/op。getrusage によるユーザー時間とシステム時間。共有マシンの影響を実行時間よりはるかに受けにくい値です）と、PostgreSQL（pg-wait-ns/op、pg-wait-%）および Redis の待ち時間を出力します。

タスク（internal/workers/reportwkr/testdata/consumerbench/tasks.jsonl.gz）は、レポートハンドラーがパブリッシュする形式でエンコードされています。最近の本番レポートのステージ、サーバー、時刻、ソース、バージョン、ドロップパターンを基に、合成アカウント、IP アドレス、タスク ID を使用しています。

スクラッチデータベース、Redis、JetStream を有効にした NATS が必要です。スクラッチデータベースには、本番環境のリストアデータ（penguinprod。読み取り専用）のスキーマと参照テーブル、および合成アカウントが格納されます。ベンチマークでは drop_reports と drop_report_extras を切り詰めます。

scripts/consumerbench/setup-db.sh   # creates penguin_cpubench and the role cpubench on 127.0.0.1:5434
# regenerate the tasks, if needed: CONSUMERBENCH_TASKS, CONSUMERBENCH_BATCH_PERMILLE, CONSUMERBENCH_SEED
CONSUMERBENCH_GENERATE=1 go test -tags consumerbench -run TestConsumerBenchGenerate ./internal/workers/reportwkr/

デフォルトでは、127.0.0.1:5434 の penguin_cpubench、127.0.0.1:16379 の Redis DB 14、127.0.0.1:4222 の NATS に接続します（CONSUMERBENCH_POSTGRES_DSN、CONSUMERBENCH_REDIS_URL、CONSUMERBENCH_NATS_URL）。続いて、次を実行します。

# one run
go test -tags consumerbench -run '^$' -bench BenchmarkConsumer -benchtime 2000x ./internal/workers/reportwkr/
# interleaved runs of variants, compared with benchstat: logging to a counting io.Discard (prod), to /dev/null
# (devnull), disabled (logoff); tracing as in production at 10% (prod), off (traceoff), at 100% (trace1); both off (off)
COUNT=10 scripts/consumerbench/run.sh bench prod logoff traceoff off devnull trace1
# CPU and allocation profiles of the ingestion, the top functions and the share of each part of the consumer
scripts/consumerbench/run.sh profile prod

出力先は $OUT です（デフォルトでは新しい一時ディレクトリが使用されます）。実行ごとに、ロードアベレージと、クラスタ上で他のセッションがアクティブにしていたクエリを $OUT/runs.log に記録します。PostgreSQL への接続はループバック経由です。この場合、書き込みシステムコールが受信側の TCP 処理も行うため、リモートサーバーへの接続時よりシステムコールの比重が大きくなります。

メンテナー

このプロジェクトは主に、以下のコントリビューターによってメンテナンスされています（アルファベット順）。

• AlvISsReimu
• GalvinGao

Penguin Statistics プロジェクトのアクティブなコントリビューターの全リストは、ウェブサイトのチームメンバーのページで確認できます。

コントリビューター

このプロジェクトは、以下のコントリビューターの協力によって成り立っています。コントリビューションはいつでも歓迎します！

ライセンス