ledger

package
v0.1.5 Latest Latest
Warning

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

 Go to latest Published: Mar 3, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	CommunicationEventRequestReceived = "request.received"
	CommunicationEventResponseStarted = "response.started"
	CommunicationEventResponseChunk   = "response.chunk"
	CommunicationEventResponseBody    = "response.body"
	CommunicationEventResponseDone    = "response.completed"
	CommunicationEventResponseError   = "response.error"
)

CommunicationEventType constants for request/response lifecycle events.

Variables

This section is empty.

Functions

This section is empty.

Types

type CommunicationEvent added in v0.1.4 

type CommunicationEvent struct {
	Timestamp   time.Time           `json:"timestamp"`
	Type        string              `json:"type"`
	TokenHash   string              `json:"token_hash,omitempty"`
	Model       string              `json:"model,omitempty"`
	Provider    string              `json:"provider,omitempty"`
	Method      string              `json:"method,omitempty"`
	Path        string              `json:"path,omitempty"`
	StatusCode  int                 `json:"status_code,omitempty"`
	ContentType string              `json:"content_type,omitempty"`
	Headers     map[string][]string `json:"headers,omitempty"`
	Body        string              `json:"body,omitempty"`
	BodyBytes   int                 `json:"body_bytes,omitempty"`
	ChunkIndex  int                 `json:"chunk_index,omitempty"`
	Stream      bool                `json:"stream,omitempty"`
	RetryCount  int                 `json:"retry_count,omitempty"`
	Error       string              `json:"error,omitempty"`
}

CommunicationEvent captures raw request/response communication details. Stored separately from RequestEntry rollups for diagnostics and replay.

type GitInfo 

type GitInfo struct {
	Branch      string `json:"branch,omitempty"`
	CommitStart string `json:"commit_start,omitempty"`
	CommitEnd   string `json:"commit_end,omitempty"`
	RepoRoot    string `json:"repo_root,omitempty"`
}

GitInfo holds git repository context for a session.

type Ledger 

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

Ledger records per-session token usage to disk in .tokenomics/.

func Open 

func Open(dir string, memory bool, events bool) (*Ledger, error)

Open creates a new Ledger session. It creates the .tokenomics/sessions/ and .tokenomics/memory/ directories if they don't exist, snapshots git context, and generates a session ID.

func (*Ledger) Close 

func (l *Ledger) Close() error

Close finalizes the session: snapshots git end state, computes rollups, writes the session JSON, and closes the memory writer.

func (*Ledger) EventsEnabled added in v0.1.4 

func (l *Ledger) EventsEnabled() bool

EventsEnabled indicates whether communication event capture is enabled.

func (*Ledger) RecordCommunicationEvent added in v0.1.4 

func (l *Ledger) RecordCommunicationEvent(ev CommunicationEvent) error

RecordCommunicationEvent appends a communication event and optionally mirrors it into memory markdown when memory logging is enabled.

func (*Ledger) RecordMemory 

func (l *Ledger) RecordMemory(tokenHash, role, model, content string) error

RecordMemory writes conversation content to the memory log.

func (*Ledger) RecordRequest 

func (l *Ledger) RecordRequest(entry RequestEntry)

RecordRequest appends a request entry to the session. Thread-safe.

func (*Ledger) SessionID 

func (l *Ledger) SessionID() string

SessionID returns the current session's ID.

type OpenClawAnalytics added in v0.1.1 

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

OpenClawAnalytics provides cost attribution and analytics by OpenClaw metadata fields.

func NewOpenClawAnalytics added in v0.1.1 

func NewOpenClawAnalytics(dir string) *OpenClawAnalytics

NewOpenClawAnalytics creates a new analytics engine for a .tokenomics directory.

func (*OpenClawAnalytics) ByMetadataKey added in v0.1.1 

func (oca *OpenClawAnalytics) ByMetadataKey(key string) (map[string]*OpenClawMetricValue, error)

ByMetadataKey aggregates metrics grouped by a specific metadata key. key should be one of: agent_id, agent_type, team, channel, skill, environment Returns map of metadata value -> aggregated metrics, sorted by total tokens descending.

func (*OpenClawAnalytics) ByTeamAndChannel added in v0.1.1 

func (oca *OpenClawAnalytics) ByTeamAndChannel() (map[string]*OpenClawMetricValue, error)

ByTeamAndChannel aggregates metrics grouped by team and channel combination. Useful for fine-grained cost breakdown for multi-team deployments. Returns map of "team/channel" -> metrics, sorted by total tokens descending.

func (*OpenClawAnalytics) FilteredSessions added in v0.1.1 

func (oca *OpenClawAnalytics) FilteredSessions(filter SessionFilter) ([]*SessionSummary, error)

FilteredSessions returns sessions matching the provided filter criteria. Used for detailed session-level analysis.

type OpenClawMetricValue added in v0.1.1 

type OpenClawMetricValue struct {
	Value               string   `json:"value"`
	RequestCount        int64    `json:"request_count"`
	InputTokens         int64    `json:"input_tokens"`
	OutputTokens        int64    `json:"output_tokens"`
	TotalTokens         int64    `json:"total_tokens"`
	CachedInputTokens   int64    `json:"cached_input_tokens,omitempty"`
	CacheCreationTokens int64    `json:"cache_creation_tokens,omitempty"`
	ReasoningTokens     int64    `json:"reasoning_tokens,omitempty"`
	ErrorCount          int64    `json:"error_count"`
	Sessions            int64    `json:"session_count"`
	ModelsUsed          []string `json:"models_used,omitempty"`
}

OpenClawMetricValue represents an aggregated metric for an OpenClaw dimension.

type ProviderMeta 

type ProviderMeta struct {
	CachedInputTokens   int    `json:"cached_input_tokens,omitempty"`
	CacheCreationTokens int    `json:"cache_creation_tokens,omitempty"`
	ReasoningTokens     int    `json:"reasoning_tokens,omitempty"`
	ActualModel         string `json:"actual_model,omitempty"`
	FinishReason        string `json:"finish_reason,omitempty"`

	RateLimitRemainingRequests int    `json:"rate_limit_remaining_requests,omitempty"`
	RateLimitRemainingTokens   int    `json:"rate_limit_remaining_tokens,omitempty"`
	RateLimitReset             string `json:"rate_limit_reset,omitempty"`
}

ProviderMeta holds normalized metadata from the provider's response.

type RequestEntry 

type RequestEntry struct {
	Timestamp         time.Time         `json:"timestamp"`
	TokenHash         string            `json:"token_hash"`
	Model             string            `json:"model"`
	Provider          string            `json:"provider"`
	InputTokens       int               `json:"input_tokens"`
	OutputTokens      int               `json:"output_tokens"`
	DurationMs        int64             `json:"duration_ms"`
	StatusCode        int               `json:"status_code"`
	Stream            bool              `json:"stream,omitempty"`
	Error             string            `json:"error,omitempty"`
	UpstreamID        string            `json:"upstream_id,omitempty"`
	UpstreamRequestID string            `json:"upstream_request_id,omitempty"`
	RetryCount        int               `json:"retry_count,omitempty"`
	FallbackModel     string            `json:"fallback_model,omitempty"`
	RuleMatches       []RuleMatchEntry  `json:"rule_matches,omitempty"`
	Metadata          map[string]string `json:"metadata,omitempty"`
	ProviderMeta      *ProviderMeta     `json:"provider_meta,omitempty"`
}

RequestEntry captures a single proxied request.

type RuleMatchEntry 

type RuleMatchEntry struct {
	Name    string `json:"name,omitempty"`
	Action  string `json:"action"`
	Message string `json:"message"`
}

RuleMatchEntry records a content rule match.

type SessionFilter added in v0.1.1 

type SessionFilter struct {
	StartTime   time.Time // Only sessions that started after this time
	EndTime     time.Time // Only sessions that ended before this time
	MetadataKey string    // Metadata key to filter by (e.g., "team")
	MetadataVal string    // Metadata value to match
	TokenHash   string    // Optional: filter by token hash prefix
}

SessionFilter describes criteria for filtering sessions.

type SessionSummary 

type SessionSummary struct {
	SessionID           string                  `json:"session_id"`
	StartedAt           string                  `json:"started_at"`
	EndedAt             string                  `json:"ended_at"`
	DurationMs          int64                   `json:"duration_ms"`
	Git                 GitInfo                 `json:"git"`
	Totals              SessionTotals           `json:"totals"`
	ByModel             map[string]*UsageRollup `json:"by_model"`
	ByProvider          map[string]*UsageRollup `json:"by_provider"`
	ByToken             map[string]*TokenRollup `json:"by_token"`
	Requests            []RequestEntry          `json:"requests"`
	CommunicationEvents []CommunicationEvent    `json:"communication_events,omitempty"`
}

SessionSummary is the top-level JSON written to sessions/<date>_<id>.json.

func ReadSessionFiles 

func ReadSessionFiles(dir string) ([]*SessionSummary, error)

ReadSessionFiles reads all session summary JSON files from the given directory.

type SessionTotals 

type SessionTotals struct {
	UsageRollup
	ErrorCount         int64 `json:"error_count"`
	RetryCount         int64 `json:"retry_count"`
	RuleViolationCount int64 `json:"rule_violation_count"`
	RateLimitCount     int64 `json:"rate_limit_count"`
}

SessionTotals extends UsageRollup with error and operational counters.

type TokenRollup 

type TokenRollup struct {
	UsageRollup
	ModelsUsed []string `json:"models_used"`
	FirstSeen  string   `json:"first_seen"`
	LastSeen   string   `json:"last_seen"`
}

TokenRollup extends UsageRollup with per-token tracking fields.

type UsageRollup 

type UsageRollup struct {
	RequestCount        int64 `json:"request_count"`
	InputTokens         int64 `json:"input_tokens"`
	OutputTokens        int64 `json:"output_tokens"`
	TotalTokens         int64 `json:"total_tokens"`
	CachedInputTokens   int64 `json:"cached_input_tokens,omitempty"`
	CacheCreationTokens int64 `json:"cache_creation_tokens,omitempty"`
	ReasoningTokens     int64 `json:"reasoning_tokens,omitempty"`
}

UsageRollup holds aggregated token counts for a grouping dimension.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.