feat(observability): 日志聚合后端 — logger环形缓冲 + GET /admin/observability/logs
- internal/logger/ring.go: Entry{time,level,source,msg} + RingBuffer(2000,满覆盖最旧,不阻塞)+ringHandler(slog旁路,Enabled委托内层,sourceOf提取source=再回落Scoped); Options.Ring非nil才包
- gateway/observability_logs.go: GET /admin/observability/logs?level=&limit= (writeAuth owner/admin) → {data:[{time(RFC3339 UTC),level,source,msg}]} 最新在前; level阈值过滤(warn=warn+error,已标注取舍); limit缺省200上限1000; 未知level400/未注入501
- routes.go注册 + observability.go SetLogBuffer(atomic.Pointer) + cmd/cyrene main.go/wireGatewayLogBuffer接线(logger先于gateway)
- 控制台/文件输出零变化; 记录只源自已产出日志,不额外打印敏感
- Docs/api-client v0.35; 测试(ring 10 + observability_logs 8 + cmd端到端2); build/vet/test绿(56)+win/darwin交叉编译
This commit is contained in:
AskaEth committed
1 parent
79589b5c9f
commit
025dd1796b
11 files changed
+850
-6
No files matched your search
@@ -31,6 +31,10 @@ type Options struct {
|
||||
Format string
|
||||
// Out is the destination writer. Defaults to os.Stderr when nil.
|
||||
Out io.Writer
|
||||
// Ring, when non-nil, additionally captures every emitted record into a
|
||||
// bounded ring buffer served by the admin observability log tail. The
|
||||
// console/file output through Out is unchanged.
|
||||
Ring *RingBuffer
|
||||
}
|
||||
|
||||
// New builds a slog.Logger from opts.
|
||||
@@ -49,7 +53,7 @@ func New(opts Options) *slog.Logger {
|
||||
handler = slog.NewTextHandler(out, handlerOpts)
|
||||
}
|
||||
|
||||
return slog.New(handler)
|
||||
return slog.New(newRingHandler(handler, opts.Ring))
|
||||
}
|
||||
|
||||
// ParseLevel maps a string level name to a slog.Level. Unknown or empty values
|
||||
|
||||
@@ -0,0 +1,202 @@
|
||||
package logger
|
||||
|
||||
import (
|
||||
"context"
|
||||
"log/slog"
|
||||
"sync"
|
||||
"time"
|
||||
)
|
||||
|
||||
// DefaultRingCapacity is how many recent log records the observability ring
|
||||
// buffer retains before the oldest is evicted. Compile-time constant.
|
||||
const DefaultRingCapacity = 2000
|
||||
|
||||
// Entry is one normalized log record as the admin observability log tail serves
|
||||
// it: {time, level, source, msg}. Time is the record's own timestamp; Source is
|
||||
// the provenance tag ("module/subfeature") when the record carried one.
|
||||
type Entry struct {
|
||||
Time time.Time
|
||||
Level string
|
||||
Source string
|
||||
Msg string
|
||||
}
|
||||
|
||||
// RingBuffer is a concurrency-safe bounded buffer of recent log entries. When
|
||||
// full the oldest entry is overwritten, so it never grows past its capacity and
|
||||
// Append never blocks or fails. It is the storage behind
|
||||
// GET /api/v1/admin/observability/logs.
|
||||
type RingBuffer struct {
|
||||
mu sync.RWMutex
|
||||
buf []Entry
|
||||
next int
|
||||
full bool
|
||||
cap int
|
||||
}
|
||||
|
||||
// NewRingBuffer builds a ring buffer holding up to capacity entries, falling
|
||||
// back to DefaultRingCapacity when capacity is not positive.
|
||||
func NewRingBuffer(capacity int) *RingBuffer {
|
||||
if capacity <= 0 {
|
||||
capacity = DefaultRingCapacity
|
||||
}
|
||||
return &RingBuffer{buf: make([]Entry, capacity), cap: capacity}
|
||||
}
|
||||
|
||||
// Append stores e, overwriting the oldest entry when the buffer is full.
|
||||
func (r *RingBuffer) Append(e Entry) {
|
||||
if r == nil {
|
||||
return
|
||||
}
|
||||
r.mu.Lock()
|
||||
defer r.mu.Unlock()
|
||||
r.buf[r.next] = e
|
||||
r.next = (r.next + 1) % r.cap
|
||||
if r.next == 0 {
|
||||
r.full = true
|
||||
}
|
||||
}
|
||||
|
||||
// Len returns how many entries are currently retained (at most the capacity).
|
||||
func (r *RingBuffer) Len() int {
|
||||
if r == nil {
|
||||
return 0
|
||||
}
|
||||
r.mu.RLock()
|
||||
defer r.mu.RUnlock()
|
||||
if r.full {
|
||||
return r.cap
|
||||
}
|
||||
return r.next
|
||||
}
|
||||
|
||||
// Snapshot returns up to limit most-recent entries, newest first. A non-positive
|
||||
// limit returns every retained entry.
|
||||
func (r *RingBuffer) Snapshot(limit int) []Entry {
|
||||
if r == nil {
|
||||
return nil
|
||||
}
|
||||
r.mu.RLock()
|
||||
defer r.mu.RUnlock()
|
||||
count := r.next
|
||||
if r.full {
|
||||
count = r.cap
|
||||
}
|
||||
if limit > 0 && limit < count {
|
||||
count = limit
|
||||
}
|
||||
out := make([]Entry, 0, count)
|
||||
for i := 0; i < count; i++ {
|
||||
idx := (r.next - 1 - i + r.cap*2) % r.cap
|
||||
out = append(out, r.buf[idx])
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// ringHandler wraps another slog.Handler: every record the inner handler emits
|
||||
// is also normalized into buf. The inner handler's own output (console/file) is
|
||||
// untouched, so installing the ring changes nothing downstream.
|
||||
type ringHandler struct {
|
||||
inner slog.Handler
|
||||
buf *RingBuffer
|
||||
attrs []slog.Attr
|
||||
}
|
||||
|
||||
// newRingHandler wraps inner so emitted records are captured into buf. A nil
|
||||
// buffer returns inner unchanged.
|
||||
func newRingHandler(inner slog.Handler, buf *RingBuffer) slog.Handler {
|
||||
if buf == nil {
|
||||
return inner
|
||||
}
|
||||
return &ringHandler{inner: inner, buf: buf}
|
||||
}
|
||||
|
||||
// Enabled delegates to the inner handler: the ring captures exactly the records
|
||||
// the configured level lets through, never more.
|
||||
func (h *ringHandler) Enabled(ctx context.Context, level slog.Level) bool {
|
||||
return h.inner.Enabled(ctx, level)
|
||||
}
|
||||
|
||||
// Handle captures rec into the ring buffer and forwards it to the inner handler.
|
||||
func (h *ringHandler) Handle(ctx context.Context, rec slog.Record) error {
|
||||
h.buf.Append(Entry{
|
||||
Time: rec.Time,
|
||||
Level: levelName(rec.Level),
|
||||
Source: h.sourceOf(rec),
|
||||
Msg: rec.Message,
|
||||
})
|
||||
return h.inner.Handle(ctx, rec)
|
||||
}
|
||||
|
||||
// WithAttrs keeps the captured attributes in sync with the child logger, so a
|
||||
// source tagged with logger.WithSource is visible to Handle.
|
||||
func (h *ringHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
|
||||
if len(attrs) == 0 {
|
||||
return h
|
||||
}
|
||||
return &ringHandler{
|
||||
inner: h.inner.WithAttrs(attrs),
|
||||
buf: h.buf,
|
||||
attrs: append(append([]slog.Attr{}, h.attrs...), attrs...),
|
||||
}
|
||||
}
|
||||
|
||||
// WithGroup keeps the group nesting in sync with the child logger.
|
||||
func (h *ringHandler) WithGroup(name string) slog.Handler {
|
||||
if name == "" {
|
||||
return h
|
||||
}
|
||||
return &ringHandler{inner: h.inner.WithGroup(name), buf: h.buf, attrs: h.attrs}
|
||||
}
|
||||
|
||||
// sourceOf resolves a record's provenance: the "source" attribute tagged by
|
||||
// logger.WithSource when present, else the "module" (+"/"+"sub") pair tagged by
|
||||
// logger.Scoped, else "".
|
||||
func (h *ringHandler) sourceOf(rec slog.Record) string {
|
||||
attrs := make([]slog.Attr, 0, len(h.attrs)+rec.NumAttrs())
|
||||
attrs = append(attrs, h.attrs...)
|
||||
rec.Attrs(func(a slog.Attr) bool {
|
||||
attrs = append(attrs, a)
|
||||
return true
|
||||
})
|
||||
if v, ok := attrValue(attrs, "source"); ok {
|
||||
return v
|
||||
}
|
||||
module, ok := attrValue(attrs, "module")
|
||||
if !ok {
|
||||
return ""
|
||||
}
|
||||
if sub, ok := attrValue(attrs, "sub"); ok && sub != "" {
|
||||
return module + "/" + sub
|
||||
}
|
||||
return module
|
||||
}
|
||||
|
||||
// attrValue returns the value of key in attrs, recursing into groups.
|
||||
func attrValue(attrs []slog.Attr, key string) (string, bool) {
|
||||
for _, a := range attrs {
|
||||
if a.Value.Kind() == slog.KindGroup {
|
||||
if v, ok := attrValue(a.Value.Group(), key); ok {
|
||||
return v, true
|
||||
}
|
||||
continue
|
||||
}
|
||||
if a.Key == key {
|
||||
return a.Value.String(), true
|
||||
}
|
||||
}
|
||||
return "", false
|
||||
}
|
||||
|
||||
// levelName maps a slog level to the wire name used by the log tail.
|
||||
func levelName(l slog.Level) string {
|
||||
switch {
|
||||
case l >= slog.LevelError:
|
||||
return "error"
|
||||
case l >= slog.LevelWarn:
|
||||
return "warn"
|
||||
case l >= slog.LevelInfo:
|
||||
return "info"
|
||||
default:
|
||||
return "debug"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,184 @@
|
||||
package logger
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"io"
|
||||
"log/slog"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
func TestRingBuffer_BoundedDropsOldest(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
ring := NewRingBuffer(3)
|
||||
for i := 0; i < 5; i++ {
|
||||
ring.Append(Entry{Time: time.Unix(int64(i), 0), Level: "info", Msg: string(rune('a' + i))})
|
||||
}
|
||||
|
||||
if got := ring.Len(); got != 3 {
|
||||
t.Fatalf("Len() = %d, want 3 (bounded)", got)
|
||||
}
|
||||
got := ring.Snapshot(0)
|
||||
if len(got) != 3 {
|
||||
t.Fatalf("Snapshot len = %d, want 3", len(got))
|
||||
}
|
||||
want := []string{"e", "d", "c"} // newest first, a/b evicted
|
||||
for i, msg := range want {
|
||||
if got[i].Msg != msg {
|
||||
t.Fatalf("Snapshot[%d].Msg = %q, want %q (got %v)", i, got[i].Msg, msg, got)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestRingBuffer_SnapshotLimit(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
ring := NewRingBuffer(5)
|
||||
for i := 0; i < 5; i++ {
|
||||
ring.Append(Entry{Level: "info", Msg: string(rune('a' + i))})
|
||||
}
|
||||
|
||||
if got := ring.Snapshot(2); len(got) != 2 || got[0].Msg != "e" || got[1].Msg != "d" {
|
||||
t.Fatalf("Snapshot(2) = %v, want newest two [e d]", got)
|
||||
}
|
||||
if got := ring.Snapshot(-1); len(got) != 5 {
|
||||
t.Fatalf("Snapshot(-1) len = %d, want all 5", len(got))
|
||||
}
|
||||
}
|
||||
|
||||
func TestRingBuffer_DefaultCapacityOnNonPositive(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
ring := NewRingBuffer(0)
|
||||
if got := cap(ring.buf); got != DefaultRingCapacity {
|
||||
t.Fatalf("capacity = %d, want default %d", got, DefaultRingCapacity)
|
||||
}
|
||||
}
|
||||
|
||||
func TestNew_RingCapturesSourceLevelAndMsg(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
var out bytes.Buffer
|
||||
ring := NewRingBuffer(8)
|
||||
log := New(Options{Level: "debug", Format: "text", Out: &out, Ring: ring})
|
||||
WithSource(log, "runtime/loop").Warn("agent stalled", "step", 3)
|
||||
|
||||
entries := ring.Snapshot(0)
|
||||
if len(entries) != 1 {
|
||||
t.Fatalf("captured %d entries, want 1", len(entries))
|
||||
}
|
||||
e := entries[0]
|
||||
if e.Level != "warn" {
|
||||
t.Fatalf("level = %q, want warn", e.Level)
|
||||
}
|
||||
if e.Source != "runtime/loop" {
|
||||
t.Fatalf("source = %q, want runtime/loop", e.Source)
|
||||
}
|
||||
if e.Msg != "agent stalled" {
|
||||
t.Fatalf("msg = %q, want %q", e.Msg, "agent stalled")
|
||||
}
|
||||
if e.Time.IsZero() {
|
||||
t.Fatal("time is zero, want the record timestamp")
|
||||
}
|
||||
// The wrapped output is unchanged: the ring is a pure side channel.
|
||||
if !strings.Contains(out.String(), "level=WARN") || !strings.Contains(out.String(), "msg=\"agent stalled\"") {
|
||||
t.Fatalf("inner output changed, got %q", out.String())
|
||||
}
|
||||
}
|
||||
|
||||
func TestNew_RingExtractsScopedSource(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
ring := NewRingBuffer(8)
|
||||
log := New(Options{Level: "debug", Format: "text", Out: io.Discard, Ring: ring})
|
||||
Scoped(log, "channel", "adapter").Info("connected")
|
||||
|
||||
entries := ring.Snapshot(0)
|
||||
if len(entries) != 1 || entries[0].Source != "channel/adapter" {
|
||||
t.Fatalf("entries = %v, want one with source channel/adapter", entries)
|
||||
}
|
||||
}
|
||||
|
||||
func TestNew_RingCapturesLevelsNewestFirst(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
ring := NewRingBuffer(8)
|
||||
log := New(Options{Level: "debug", Format: "text", Out: io.Discard, Ring: ring})
|
||||
log.Debug("d")
|
||||
log.Info("i")
|
||||
log.Warn("w")
|
||||
log.Error("e")
|
||||
|
||||
entries := ring.Snapshot(0)
|
||||
if len(entries) != 4 {
|
||||
t.Fatalf("captured %d entries, want 4", len(entries))
|
||||
}
|
||||
wantLevels := []string{"error", "warn", "info", "debug"}
|
||||
wantMsgs := []string{"e", "w", "i", "d"}
|
||||
for i := range wantLevels {
|
||||
if entries[i].Level != wantLevels[i] || entries[i].Msg != wantMsgs[i] {
|
||||
t.Fatalf("entries[%d] = %+v, want level=%s msg=%s", i, entries[i], wantLevels[i], wantMsgs[i])
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestNew_RingHonorsConfiguredLevel(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
ring := NewRingBuffer(8)
|
||||
log := New(Options{Level: "warn", Format: "text", Out: io.Discard, Ring: ring})
|
||||
log.Info("dropped")
|
||||
log.Warn("kept")
|
||||
|
||||
entries := ring.Snapshot(0)
|
||||
if len(entries) != 1 || entries[0].Msg != "kept" {
|
||||
t.Fatalf("entries = %v, want only the warn record", entries)
|
||||
}
|
||||
}
|
||||
|
||||
func TestNew_NilRingIsTransparent(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
var out bytes.Buffer
|
||||
log := New(Options{Level: "debug", Format: "text", Out: &out})
|
||||
log.Info("hello")
|
||||
if !strings.Contains(out.String(), "msg=hello") {
|
||||
t.Fatalf("logger without a ring stopped emitting, got %q", out.String())
|
||||
}
|
||||
}
|
||||
|
||||
func TestRingBuffer_NilReceiverIsSafe(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
var ring *RingBuffer
|
||||
ring.Append(Entry{Msg: "x"})
|
||||
if got := ring.Snapshot(0); got != nil {
|
||||
t.Fatalf("Snapshot on nil = %v, want nil", got)
|
||||
}
|
||||
if got := ring.Len(); got != 0 {
|
||||
t.Fatalf("Len on nil = %d, want 0", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestLevelName(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
tests := []struct {
|
||||
in slog.Level
|
||||
want string
|
||||
}{
|
||||
{slog.LevelDebug, "debug"},
|
||||
{slog.LevelInfo, "info"},
|
||||
{slog.LevelWarn, "warn"},
|
||||
{slog.LevelError, "error"},
|
||||
{slog.LevelError + 4, "error"},
|
||||
{slog.LevelDebug - 4, "debug"},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
if got := levelName(tt.in); got != tt.want {
|
||||
t.Fatalf("levelName(%v) = %q, want %q", tt.in, got, tt.want)
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user