logstream

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 10, 2026 License: Apache-2.0 Imports: 2 Imported by: 0

Documentation

Overview

Package logstream implements the transport-agnostic pub/sub hub behind the live log stream. It fans LogEvent values out to every subscriber without ever blocking the publisher; SSE framing and the HTTP surface live in internal/api/logs.go, so the hub has no HTTP dependency.

Index

Constants

View Source
const (
	TypeRequestComplete = "request.complete"
	TypeLoopBlocked     = "loop_blocked"
	TypeBudgetExceeded  = "budget_exceeded"
	TypeBudgetLevel     = "budget_level"
	TypeCostAlert       = "cost_alert"
	TypeSettingsUpdated = "settings.updated"
)

Event type discriminators — the "type" field on the wire. TypeRequestStart is reserved for future use and never emitted in the MVP.

Variables

This section is empty.

Functions

This section is empty.

Types

type Hub

type Hub struct {
	// contains filtered or unexported fields
}

Hub is a fan-out pub/sub hub. Publish delivers a LogEvent to every current subscriber without ever blocking: a slow subscriber drops the oldest buffered event (then the new one on a still-full buffer) and counts the drop. It is safe for concurrent use.

func NewHub

func NewHub(resolver TenantNameResolver) *Hub

NewHub builds a Hub. resolver may be nil, in which case TenantName is never re-resolved at publish time.

func (*Hub) Len

func (h *Hub) Len() int

Len returns the number of currently registered subscribers. It exists for tests and diagnostics.

func (*Hub) Publish

func (h *Hub) Publish(ev LogEvent)

Publish delivers ev to every registered subscriber. It resolves TenantName via the injected resolver (once, before fan-out) when the publisher left it empty and a tenant is bound; otherwise the publisher's TenantName is kept verbatim (the budget_exceeded path sets it directly from auth.Tenant). It never blocks: a subscriber with a full buffer first drops its oldest queued event, then, if the buffer is still full, drops the new event instead. Both drops are counted under the subscriber's mutex so concurrent publishers cannot interleave on one channel.

func (*Hub) Subscribe

func (h *Hub) Subscribe(_ context.Context, buf int) *Subscription

Subscribe registers a new subscriber with a buffered channel of size buf (buf < 1 is treated as 1) and returns its Subscription. The context is accepted so the SSE handler can pass the request context, but cancellation is the caller's responsibility: the handler selects on r.Context().Done() and defers Close. A cancelled context alone does NOT unregister.

type LogEvent

type LogEvent struct {
	Type      string `json:"type"`
	Level     string `json:"level"`
	Timestamp int64  `json:"timestamp"`

	TenantID    string `json:"tenant_id,omitempty"`
	TenantName  string `json:"tenant_name,omitempty"`
	AgentID     string `json:"agent_id,omitempty"`
	Model       string `json:"model,omitempty"`
	ProjectName string `json:"project_name,omitempty"`

	PromptTokens     int64 `json:"prompt_tokens,omitempty"`
	CompletionTokens int64 `json:"completion_tokens,omitempty"`

	CostMicroUSD       int64 `json:"cost_micro_usd,omitempty"`
	SavedCostMicroUSD  int64 `json:"saved_cost_micro_usd,omitempty"`
	BudgetMicroUSD     int64 `json:"budget_micro_usd,omitempty"`     // daily budget figure (budget_level)
	SpentMicroUSD      int64 `json:"spent_micro_usd,omitempty"`      // actual spend at the moment of the event
	MonthlyBudgetMicro int64 `json:"monthly_budget_micro,omitempty"` // per-caller monthly budget (budget_exceeded)

	StatusCode    int    `json:"status_code,omitempty"`
	FirstBlock    bool   `json:"first_block,omitempty"`
	Reason        string `json:"reason,omitempty"`
	RetryAfter    int    `json:"retry_after,omitempty"`
	ThresholdPct  int    `json:"threshold_pct,omitempty"`
	DroppedEvents uint64 `json:"dropped_events,omitempty"`
}

LogEvent is one live stream event. All money fields are integer micro-dollars (µUSD); float USD conversion happens only at the JSON boundary in the API layer. Timestamp is Unix epoch seconds (UTC), like db.RequestLog.Timestamp.

type Subscription

type Subscription struct {
	C <-chan LogEvent
	// contains filtered or unexported fields
}

Subscription is a live delivery handle. Reading from C yields buffered events in FIFO order. Close unsubscribes from the hub and closes C; it is idempotent and safe to call from any goroutine.

func (*Subscription) Close

func (s *Subscription) Close()

Close unsubscribes s from the hub and closes its delivery channel. It is idempotent. A Publish already delivering to this subscriber completes before the channel closes: Close takes the hub's write lock, which blocks until every in-flight Publish (which holds the read lock across its fan-out) has finished.

func (*Subscription) Dropped

func (s *Subscription) Dropped() uint64

Dropped returns the number of events this subscriber has dropped: drop-oldest plus drop-new on a persistently full buffer.

func (*Subscription) QueueDepth

func (s *Subscription) QueueDepth() int

QueueDepth returns the number of events currently buffered for this subscriber. It powers the stream_stats control event's queue_depth field.

type TenantNameResolver

type TenantNameResolver func(tenantID string) (string, bool)

TenantNameResolver maps a tenant_id to its display team name. The bool is false when the tenant is unknown — including the legacy "" bucket, which has no tenants row. A nil resolver leaves TenantName exactly as the publisher set it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL