Skip to main content

Panduan Operasi

Gambaran keseluruhan​

Yabanin ialah sistem tiga perkhidmatan:

PerkhidmatanPerananPort lalai
gatewayproxy API HTTP + penghalaan8082 / 9090
adminPanel pentadbir + API analitik8086
loggerdPengambilan peristiwa → penulis Postgres8085

Modul: github.com/reireirei/yabanin

Versi Go: 1.25.0

Binaan: go build ./... dari akar monorepo.


Endpoint perkhidmatan​

Gerbang (pkg/gateway/gateway.go)​

AlamatTujuan
:8082API HTTP (proxy pemajuan)
:9090Pelayan 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)​

AlamatTujuan
:8086API 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)​

AlamatTujuan
:8085API 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​

PerkhidmatanEndpointResponsKebergantungan yang disemak
GerbangGET /healthzJSON: {"status":"ok","redis":{"status":"up"}} atau "down"Ketersambungan Redis
PentadbirGET /healthTeks biasa: okTiada
LoggerdGET /healthzHTTP 200 OKTiada

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)​

MetrikJenisLabelPenerangan
gateway_requests_totalKauntermethod, path, statusJumlah permintaan HTTP yang dikendalikan
gateway_request_duration_secondsHistogrammethod, path, statusKependaman permintaan dalam saat
gateway_upstream_first_token_secondsHistogramprovider, modelMasa ke token pertama yang distrim (permintaan SSE sahaja; baldi 0.005s–10s)
gateway_upstream_requests_totalKaunterprovider, model, statusPermintaan huluan selepas penghalaan
gateway_retry_totalKaunterattempt, statusCubaan semula dalam model (pengangkutan/429/5xx) mengikut nombor percubaan
gateway_fallback_totalKaunterfrom, to, reasonPenyiapan lompatan rantai sandaran
cache_hits_totalKauntertype, org_idCarian 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​

MetrikJenisLabelPenerangan
gateway_events_in_flightTolok(tiada)Bilangan mesej yang sedang diproses
gateway_events_consumed_totalKaunterevent_typeJumlah peristiwa yang berjaya digunakan

Jenis peristiwa bagi events_consumed_total:

  • request.completed — Permintaan proxy yang berjaya dilog
  • request.failed — Permintaan proxy yang gagal dilog
  • Mana-mana rentetan lain daripada medan event_type dalam strim Redis (peristiwa generik)

Metrik pemutus litar (Gerbang)​

MetrikJenisLabelPenerangan
gateway_circuit_stateTolok(tiada)Keadaan pemutus litar semasa (lihat di bawah)
gateway_circuit_failuresKaunter(tiada)Jumlah peristiwa pemutus litar yang tercetus
gateway_circuit_recoveriesKaunter(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 persekitaranPeneranganLalai
YABANIN_OTEL_ENDPOINTURL endpoint OTLP/HTTP (cth., http://localhost:4318)(dilumpuhkan)
YABANIN_OTEL_SAMPLE_RATEKadar pensampelan jejak, nombor apung dalam [0.0, 1.0]1.0

Pengeksport​

  • Protokol: OTLP/HTTP (bukan gRPC)
  • Pakej penjejakan (pkg/tracing) memulakan pengeksport otlptracehttp dan mendaftarkan TracerProvider global.
  • 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​

  1. Redis tepat — SHA-256 badan permintaan (kunci merangkumi org + model).
  2. pg tepat (ikut serta, YABANIN_CACHE_PG_EXACT_LOOKUP) — sandaran Postgres selepas kehilangan Redis.
  3. 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 permintaanGaris dasar kontrafaktual
Hit cachePenggunaan 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 ituPerbelanjaan 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_mode organisasi menjadi sesuatu selain disabled.
  • 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 mengikut model_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_calls yang 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 ubahPerkhidmatanPeneranganLalai
YABANIN_OTEL_ENDPOINTGerbang, LoggerdEndpoint pengeksport jejak OTLP/HTTP(dilumpuhkan)
YABANIN_OTEL_SAMPLE_RATEGerbang, LoggerdKadar pensampelan jejak (0.0–1.0)1.0
LISTEN_ADDRPentadbirAlamat dengar HTTP (cth., :8086):8086

Konfigurasi Redis Streams (Loggerd)​

PemalarNilaiPenerangan
consumerGrouploggerd-workersNama kumpulan pengguna Redis Streams
consumerNameloggerd-0Pengecam pengguna dalam kumpulan
batchSize100Bilangan mesej maksimum bagi setiap panggilan XREADGROUP
idleTimeout1000msTempoh blok bagi strim kosong
defaultStreamevents:queueNama strim Redis lalai
maxRetries3Bilangan cubaan semula sebelum DLQ
dlqTTL7dTTL pada kunci kaunter cubaan semula
pelReclaimTimeout5mSelang tuntutan semula mesej PEL yang basi
msgSeenTTL24hTamat tempoh kunci penyahduplikatan

DLQ (Baris Gilir Surat Mati)​

  • Nama strim: events:queue:dlq
  • Mesej yang melebihi maxRetries dipindahkan 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​

  1. Semak log bagi ralat permulaan (sambungan Redis, kolam DB).
  2. Sahkan pemboleh ubah persekitaran — pastikan YABANIN_OTEL_ENDPOINT dan YABANIN_OTEL_SAMPLE_RATE mengikut format yang dijangka jika penjejakan dikehendaki.
  3. Semak konflik port: setiap perkhidmatan mengikat port yang berbeza (gerbang 8082/9090, pentadbir 8086, loggerd 8085).

Kesihatan gerbang gagal​

  1. 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]))
  1. Tapis mengikut label method dan path untuk mengenal pasti endpoint yang perlahan.
  2. Semak kesihatan perkhidmatan huluan — gerbang memajukan permintaan ke bahagian belakang yang dikonfigurasi.

Peristiwa tidak muncul dalam Postgres (Loggerd)​

  1. 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
  1. Semak ketersambungan Postgres — perkhidmatan loggerd memerlukan kolam DB untuk memasukkan request_logs.
  2. 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:

  1. Semak ralat aplikasi dalam log (cth., kegagalan tulis DB).
  2. 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):

  1. Perkhidmatan huluan berkemungkinan tidak sihat atau mengalami kadar ralat yang tinggi.
  2. Semak kesihatan perkhidmatan huluan secara langsung.
  3. Pantau kaunter gateway_circuit_failures bagi jumlah kiraan pencetusan.
  4. 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​

ImejCernaan asasPenerangan
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 kerjaPencetusPenerangan
ci.ymlTolakan ke main, PRBina, lint, uji, tolakan Docker
vulncheck.ymlMingguan (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