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 ¶
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 ¶
Len returns the number of currently registered subscribers. It exists for tests and diagnostics.
func (*Hub) Publish ¶
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 ¶
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.