Panduan Operasi
Gambaran keseluruhan
Yabanin ialah sistem tiga perkhidmatan:
| Perkhidmatan | Peranan | Port lalai |
|---|---|---|
gateway | proxy API HTTP + penghalaan | 8082 / 9090 |
admin | Panel pentadbir + API analitik | 8086 |
loggerd | Pengambilan peristiwa → penulis Postgres | 8085 |
Modul: github.com/reireirei/yabanin
Versi Go: 1.25.0
Binaan: go build ./... dari akar monorepo.
Endpoint perkhidmatan
Gerbang (pkg/gateway/gateway.go)
| Alamat | Tujuan |
|---|---|
:8082 | API HTTP (proxy pemajuan) |
:9090 | Pelayan pentadbir (metrik, penjejakan) |
- Kesihatan:
GET http://localhost:8082/healthz— memulangkan JSON dengan status ketersambungan Redis. - Metrik:
GET http://localhost:9090/metrics— format eksposisi Prometheus. - Penjejakan: pengeksport OTLP/HTTP. Dikonfigurasi melalui pemboleh ubah persekitaran (lihat di bawah).
Perkhidmatan pentadbir (services/admin/cmd/main.go)
| Alamat | Tujuan |
|---|---|
:8086 | API HTTP (pentadbir + analitik) |
- Laluan:
/auth/*,/api/analytics/* - Kesihatan:
GET http://localhost:8086/health— memulangkan"ok"dengan 200. - Metrik:
GET http://localhost:8086/metrics— format eksposisi Prometheus. - Tindihan port: Ditetapkan melalui kunci konfigurasi
listen_addr.
Perkhidmatan Loggerd (services/loggerd/cmd/main.go)
| Alamat | Tujuan |
|---|---|
:8085 | API HTTP (pengambilan peristiwa) |
- Kesihatan:
GET http://localhost:8085/healthz— memulangkan 200 OK. - Penjejakan: pengeksport OTLP/HTTP. Dikonfigurasi melalui pemboleh ubah persekitaran (lihat di bawah).
Semakan kesihatan
| Perkhidmatan | Endpoint | Respons | Kebergantungan yang disemak |
|---|---|---|---|
| Gerbang | GET /healthz | JSON: {"status":"ok","redis":{"status":"up"}} atau "down" | Ketersambungan Redis |
| Pentadbir | GET /health | Teks biasa: ok | Tiada |
| Loggerd | GET /healthz | HTTP 200 OK | Tiada |
Butiran kesihatan gerbang
Endpoint kesihatan gerbang melakukan PING ke Redis. Respons merangkumi:
{
"status": "ok",
"redis": {
"status": "up"
}
}
Jika Redis tidak dapat dihubungi, medan redis.status menjadi "down" dan status keseluruhan mencerminkan keadaan merosot. Ini berguna untuk kuar liveness/readiness Kubernetes atau semakan kesihatan pengimbang beban.
Metrik
Semua metrik didaftarkan di bawah subsistem gateway melalui Prometheus client-go (github.com/prometheus/client_golang/prometheus). Ia didedahkan dalam format eksposisi Prometheus standard pada endpoint /metrics setiap perkhidmatan.
Metrik permintaan (Gerbang)
| Metrik | Jenis | Label | Penerangan |
|---|---|---|---|
gateway_requests_total | Kaunter | method, path, status | Jumlah permintaan HTTP yang dikendalikan |
gateway_request_duration_seconds | Histogram | method, path, status | Kependaman permintaan dalam saat |
gateway_upstream_first_token_seconds | Histogram | provider, model | Masa ke token pertama yang distrim (permintaan SSE sahaja; baldi 0.005s–10s) |
gateway_upstream_requests_total | Kaunter | provider, model, status | Permintaan huluan selepas penghalaan |
gateway_retry_total | Kaunter | attempt, status | Cubaan semula dalam model (pengangkutan/429/5xx) mengikut nombor percubaan |
gateway_fallback_total | Kaunter | from, to, reason | Penyiapan lompatan rantai sandaran |
cache_hits_total | Kaunter | type, org_id | Carian cache respons mengikut jenis (exact/semantic/miss, termasuk miss) |
Histogram token pertama serta kaunter cubaan semula/sandaran menyokong lajur first_token_ms, attempt_count dan retry_count yang disimpan dalam request_logs (migrasi 0011) dan dipaparkan dalam peneroka permintaan pentadbir (/api/organizations/{id}/requests[/stats]).
Metrik Loggerd
| Metrik | Jenis | Label | Penerangan |
|---|---|---|---|
gateway_events_in_flight | Tolok | (tiada) | Bilangan mesej yang sedang diproses |
gateway_events_consumed_total | Kaunter | event_type | Jumlah peristiwa yang berjaya digunakan |
Jenis peristiwa bagi events_consumed_total:
request.completed— Permintaan proxy yang berjaya dilogrequest.failed— Permintaan proxy yang gagal dilog- Mana-mana rentetan lain daripada medan
event_typedalam strim Redis (peristiwa generik)
Metrik pemutus litar (Gerbang)
| Metrik | Jenis | Label | Penerangan |
|---|---|---|---|
gateway_circuit_state | Tolok | (tiada) | Keadaan pemutus litar semasa (lihat di bawah) |
gateway_circuit_failures | Kaunter | (tiada) | Jumlah peristiwa pemutus litar yang tercetus |
gateway_circuit_recoveries | Kaunter | (tiada) | Jumlah peristiwa pemulihan pemutus litar |
Keadaan pemutus litar (dikodkan sebagai nilai integer pada tolok):
0— CLOSED: Operasi biasa, permintaan mengalir.1— OPEN: Litar tercetus; permintaan ditolak tanpa dimajukan.2— HALF_OPEN: Permintaan kuar dibenarkan; jika berjaya, beralih ke CLOSED.
Penjejakan
Kedua-dua perkhidmatan Gerbang dan Loggerd menyokong penjejakan teragih melalui OpenTelemetry.
Konfigurasi
| Pemboleh ubah persekitaran | Penerangan | Lalai |
|---|---|---|
YABANIN_OTEL_ENDPOINT | URL endpoint OTLP/HTTP (cth., http://localhost:4318) | (dilumpuhkan) |
YABANIN_OTEL_SAMPLE_RATE | Kadar pensampelan jejak, nombor apung dalam [0.0, 1.0] | 1.0 |
Pengeksport
- Protokol: OTLP/HTTP (bukan gRPC)
- Pakej penjejakan (
pkg/tracing) memulakan pengeksportotlptracehttpdan mendaftarkanTracerProviderglobal. - Pensampelan span digunakan pada aras penyedia menggunakan kadar sampel yang dikonfigurasi.
Penggunaan dalam kod
Perkhidmatan memanggil fungsi permulaan penjejakan semasa mula:
// Gateway (pkg/gateway/gateway.go)
if err := tracing.Init(ctx, logger); err != nil {
// log warning but do not fail startup
}
// Loggerd (services/loggerd/cmd/main.go)
if err := tracing.Init(ctx, logger); err != nil {
// log warning but do not fail startup
}
Perkhidmatan pentadbir tidak mempunyai instrumentasi penjejakan.
Tingkah laku cache respons
Tertib carian
- Redis tepat — SHA-256 badan permintaan (kunci merangkumi org + model).
- pg tepat (ikut serta,
YABANIN_CACHE_PG_EXACT_LOOKUP) — sandaran Postgres selepas kehilangan Redis. - Semantik — carian ANN pgvector atas pembenaman
cache_entries.
Klien boleh memintas carian dan storan bagi setiap permintaan dengan Cache-Control: no-store.
Semantik keserupaan
pgvector <=> ialah jarak kosinus (1 − keserupaan, julat 0..2). Gerbang melaporkan X-Cache-Similarity sebagai keserupaan kosinus = 1 − distance (julat −1..1); entri ialah hit hanya apabila keserupaan ≥ ambang (lalai 0.95, jadi jarak ≤ 0.05). Hit tepat melaporkan 1.0000. Prompt sampah tidak boleh sekali-kali mendapat skor melebihi ambang — nilai X-Cache-Similarity yang lebih besar daripada 1 dalam log/metrik menandakan binaan yang lebih lama daripada pembetulan penyongsangan jarak.
Klien penstriman
Hit cache bagi permintaan stream: true dimainkan semula sebagai bingkai SSE chat.completion.chunk kanonikal (Content-Type: text/event-stream, baris data: ..., penamat data: [DONE]) — SDK serasi OpenAI melihat strim biasa. Hit cache membawa X-Cache: EXACT|PG_EXACT|SEMANTIC.
Apa yang disimpan daripada respons yang distrim: bingkai penyiapan pertama yang boleh dihuraikan, dengan objek usage daripada bingkai akhir dibawa bersama. Entri cache yang cacat dianggap sebagai miss (permintaan dilayan secara baharu), tidak sekali-kali dimainkan semula dalam keadaan rosak.
Semantik penjimatan
request_logs.counterfactual_cost_usd ialah garis dasar penjimatan setiap baris dan bergantung pada cara permintaan dilayan:
| Kelas permintaan | Garis dasar kontrafaktual |
|---|---|
| Hit cache | Penggunaan berharga bagi penyiapan yang dicache (kos yang akan ditanggung permintaan di huluan); 0 apabila penggunaan tidak diketahui |
| Dihalakan peringkat (dilayan pengelas) | Penggunaan berharga pada model yang diminta klien (routing_decision.from) |
| Selain itu | Perbelanjaan sebenar (tiada penjimatan dituntut tanpa pengoptimuman) |
Akibat bagi mentafsir papan pemuka:
- Peratusan penjimatan ialah
(SUM(counterfactual) − SUM(actual)) / SUM(counterfactual); baris dengan garis dasar yang tidak diketahui menyumbang 0/0 — ia menolak ke arah 0 dan bukannya mereka-reka penjimatan. - Penjimatan penghalaan negatif bermakna: pengelas menghalakan ke model yang lebih mahal daripada yang diminta klien.
- Penghalaan peringkat (dan oleh itu penjimatan penghalaan) memerlukan
routing_modeorganisasi menjadi sesuatu selaindisabled. - Lensa berbeza mengikut skrin: laporan penjimatan mengelompokkan model teratas mengikut
model_requested(hasil setiap permintaan — perbelanjaan yang dihalakan jatuh pada model yang diminta klien), laporan kos mengelompokkan mengikutmodel_used(atribusi perbelanjaan kepada model yang sebenarnya melayan).
Mengelompokkan permintaan kepada tugas
Permintaan dikelompokkan kepada tugas logik oleh pemanggil: hantar pengepala X-Yabanin-Task (format [A-Za-z0-9._:-]{1,128}, nilai tidak sah ditolak dengan 400; YABANIN_TASK menetapkan lalai peringkat pelaksanaan bagi pemanggil tanpa pengepala). Butiran dan treler setiap commit: docs/agent-governance.md.
Tempat untuk menganalisis kumpulan tugas: skrin Tugas (kos setiap tugas / kontrafaktual / penjimatan, eksport CSV) dan penapis Tugas Peneroka Permintaan (menskop jadual dan jalur statistik kepada satu tugas; skop ialah sebahagian daripada URL, jadi paparan yang ditapis boleh dikongsi).
Panggilan alat
Dua paparan panggilan alat/fungsi yang diminta oleh model:
- setiap permintaan — pemeriksa Peneroka menghuraikan sampel respons yang disimpan (penyiapan bukan penstriman dan sampel SSE yang distrim sama-sama; serpihan delta dipasang semula menjadi satu panggilan yang boleh dibaca). Argumen dipaparkan seperti yang disimpan; mod privasi menopengnya.
- merentas permintaan — skrin Panggilan alat mengagregat jadual
tool_callsyang diisi oleh loggerd daripada sampel yang sama: jumlah, alat teratas dengan bahagian dan kali terakhir digunakan, penggunaan setiap model (berskop organisasi, tetingkap 30 hari). Baris wujud hanya bagi panggilan yang dihurai: sampel terpotong atau tidak boleh dihurai dibaca sebagai ketiadaan, tidak sekali-kali sebagai penggunaan sifar. Sampel distrim yang bersejarah (pra-jadual) tidak diisi semula dan kekal untuk pemeriksa sahaja.
Pemboleh ubah konfigurasi
Pemboleh ubah persekitaran
| Pemboleh ubah | Perkhidmatan | Penerangan | Lalai |
|---|---|---|---|
YABANIN_OTEL_ENDPOINT | Gerbang, Loggerd | Endpoint pengeksport jejak OTLP/HTTP | (dilumpuhkan) |
YABANIN_OTEL_SAMPLE_RATE | Gerbang, Loggerd | Kadar pensampelan jejak (0.0–1.0) | 1.0 |
LISTEN_ADDR | Pentadbir | Alamat dengar HTTP (cth., :8086) | :8086 |
Konfigurasi Redis Streams (Loggerd)
| Pemalar | Nilai | Penerangan |
|---|---|---|
consumerGroup | loggerd-workers | Nama kumpulan pengguna Redis Streams |
consumerName | loggerd-0 | Pengecam pengguna dalam kumpulan |
batchSize | 100 | Bilangan mesej maksimum bagi setiap panggilan XREADGROUP |
idleTimeout | 1000ms | Tempoh blok bagi strim kosong |
defaultStream | events:queue | Nama strim Redis lalai |
maxRetries | 3 | Bilangan cubaan semula sebelum DLQ |
dlqTTL | 7d | TTL pada kunci kaunter cubaan semula |
pelReclaimTimeout | 5m | Selang tuntutan semula mesej PEL yang basi |
msgSeenTTL | 24h | Tamat tempoh kunci penyahduplikatan |
DLQ (Baris Gilir Surat Mati)
- Nama strim:
events:queue:dlq - Mesej yang melebihi
maxRetriesdipindahkan ke sini dengan medan:original_stream,retry_count,error, dan semua nilai mesej asal. - Kunci kaunter cubaan semula mengikut corak
dlq:retry:{stream}:{group}:{msg_id}dengan TTL 7 hari.
Tuntutan semula PEL (Senarai Entri Tertunggak)
Setiap 5 minit, loggerd mengimbas entri tertunggak kumpulan pengguna untuk mesej yang melahu lebih lama daripada 5 minit dan menuntutnya semula melalui XCLAIM kepada pengguna "reclaimer". Mesej yang dituntut semula dan gagal diproses dihantar ke DLQ selepas satu lagi kegagalan pemprosesan.
Runbook
Perkhidmatan tidak dapat dimulakan
- Semak log bagi ralat permulaan (sambungan Redis, kolam DB).
- Sahkan pemboleh ubah persekitaran — pastikan
YABANIN_OTEL_ENDPOINTdanYABANIN_OTEL_SAMPLE_RATEmengikut format yang dijangka jika penjejakan dikehendaki. - Semak konflik port: setiap perkhidmatan mengikat port yang berbeza (gerbang 8082/9090, pentadbir 8086, loggerd 8085).
Kesihatan gerbang gagal
curl http://localhost:8082/healthz— semak JSON respons.
Jika redis.status ialah "down":
- Sahkan Redis berjalan dan boleh dicapai daripada hos gerbang.
- Semak parameter sambungan Redis (hos, port, kata laluan) dalam konfigurasi.
- Cari isu rangkaian/tembok api antara gerbang dan Redis.
Kependaman permintaan tinggi
Tanya Prometheus bagi gateway_request_duration_seconds:
histogram_quantile(0.95, rate(gateway_request_duration_seconds_bucket[5m]))
- Tapis mengikut label
methoddanpathuntuk mengenal pasti endpoint yang perlahan. - Semak kesihatan perkhidmatan huluan — gerbang memajukan permintaan ke bahagian belakang yang dikonfigurasi.
Peristiwa tidak muncul dalam Postgres (Loggerd)
- Semak kesihatan:
curl http://localhost:8085/healthz
Sahkan strim Redis mempunyai mesej:
redis-cli XRANGE events:queue - + COUNT 10
Semak status kumpulan pengguna:
redis-cli XINFO CONSUMERS events:queue loggerd-workers
Semak entri tertunggak bagi mesej yang tersekat:
redis-cli XPENDING events:queue loggerd-workers
- Semak ketersambungan Postgres — perkhidmatan loggerd memerlukan kolam DB untuk memasukkan
request_logs. - Periksa log bagi ralat XREADGROUP atau kegagalan XACK.
Mesej tersekat dalam Senarai Entri Tertunggak (PEL)
Mesej terkumpul dalam PEL apabila dihantar kepada pengguna tetapi tidak diakui (XACK). Perkhidmatan loggerd menuntut semula mesej basi secara automatik setiap 5 minit.
Jika anda melihat tunggakan yang besar:
- Semak ralat aplikasi dalam log (cth., kegagalan tulis DB).
- Sahkan Postgres menerima sambungan dan mempunyai kapasiti yang mencukupi.
Mesej yang gagal diproses selepas 3 cubaan semula dipindahkan ke DLQ (events:queue:dlq). Periksa DLQ:
redis-cli XRANGE events:queue:dlq - + COUNT 10
Pemutus litar tercetus
Jika gateway_circuit_state membaca 1 (OPEN):
- Perkhidmatan huluan berkemungkinan tidak sihat atau mengalami kadar ralat yang tinggi.
- Semak kesihatan perkhidmatan huluan secara langsung.
- Pantau kaunter
gateway_circuit_failuresbagi jumlah kiraan pencetusan. - Apabila litar beralih ke HALF_OPEN (
2), permintaan kuar akan dihantar. Jika berjaya, ia menutup (0).
Pemeriksaan DLQ
Untuk melihat mesej racun:
redis-cli XRANGE events:queue:dlq - + COUNT 50
Setiap entri DLQ mengandungi: original_stream, retry_count, error, dan semua medan mesej asal. Mesej boleh diproses semula dengan membaca daripada strim DLQ dan menerbitkan semula ke strim utama, atau dengan membetulkan isu asas dan membiarkan sistem menyambung semula pemprosesan biasa.
Cadangan amaran
Contoh peraturan Prometheus
# Gateway requests exceeding 95th percentile 2s latency over 5 minutes
- alert: HighRequestLatency
expr: histogram_quantile(0.95, rate(gateway_request_duration_seconds_bucket[5m])) > 2
for: 5m
labels:
severity: warning
# Circuit breaker open
- alert: CircuitBreakerOpen
expr: gateway_circuit_state == 1
for: 0m
labels:
severity: critical
# Events queue backlog (in-flight > threshold)
- alert: HighEventBacklog
expr: gateway_events_in_flight > 500
for: 5m
labels:
severity: warning
# Event consumption rate drops to zero
- alert: NoEventsConsumed
expr: rate(gateway_events_consumed_total[5m]) == 0 and gateway_events_in_flight == 0
for: 10m
labels:
severity: critical
# Circuit breaker failure rate increasing
- alert: CircuitBreakerTrippingFrequently
expr: increase(gateway_circuit_failures[1h]) > 5
for: 0m
labels:
severity: warning
Aras pengelogan
Semua perkhidmatan menggunakan log/slog Go. Pelaksanaan pengeluaran sepatutnya dijalankan pada aras INFO. Tetapkan aras log melalui pemboleh ubah persekitaran SLOG_LEVEL (atau konfigurasi pengendali slog yang setara).
- DEBUG: Butiran aras mesej yang terperinci, berguna untuk penyahpepijatan DLQ.
- INFO: Peristiwa kitar hayat perkhidmatan, operasi yang berjaya.
- WARN: Isu yang boleh dipulihkan (amaran XACK, kegagalan SETNX nyahdup).
- ERROR: Kegagalan yang memerlukan perhatian (ralat tulis DB, kehilangan ketersambungan Redis).
Imej Docker
| Imej | Cernaan asas | Penerangan |
|---|---|---|
golang:1.25.0-alpine3.22 | @sha256:... | Imej binaan Go |
alpine:3.22 | @sha256:... | Masa jalan (berbilang peringkat) |
Imej Docker disemat mengikut cernaan SHA-256 dalam aliran kerja GitHub Actions (.github/workflows/ci.yml). Lihat file aliran kerja untuk cernaan tepat dan tarikh binaan semula.
CI/CD
Aliran kerja GitHub Actions
| Aliran kerja | Pencetus | Penerangan |
|---|---|---|
ci.yml | Tolakan ke main, PR | Bina, lint, uji, tolakan Docker |
vulncheck.yml | Mingguan (Isnin 00:00 UTC) | govulncheck pada kebergantungan |
Dependabot
Kemas kini kebergantungan diurus melalui Dependabot dengan dua ekosistem:
- gomod: Jadual mingguan, gabung automatik bagi versi tampalan.
- docker: Jadual mingguan, gabung automatik bagi versi tampalan (imej disemat mengikut cernaan).
Rujukan pantas
# Run all services locally (requires Redis + Postgres)
go run ./cmd/yabanin gateway
go run ./services/admin/
go run ./services/loggerd/
# Health checks
curl http://localhost:8082/healthz # Gateway
curl http://localhost:8086/health # Admin
curl http://localhost:8085/healthz # Loggerd
# Metrics
curl http://localhost:9090/metrics # Gateway admin server
curl http://localhost:8086/metrics # Admin service
# Redis DLQ inspection
redis-cli XRANGE events:queue:dlq - + COUNT 10