store

Documentation

Index

• Constants
• type MonthInfo
• type ServiceInfo
• type ServiceSummary
• type SpanSummary
• type Store
  • func Open(path string, retentionDays int) (*Store, error)
  • func (s *Store) BucketStats() ([]ServiceInfo, error)
  • func (s *Store) Cleanup() error
  • func (s *Store) Close() error
  • func (s *Store) DeleteService(service string) error
  • func (s *Store) GetSpanTree(spanID []byte) (traceID string, spans []SpanSummary, err error)
  • func (s *Store) GetSpans(service string, limit int) ([]SpanSummary, error)
  • func (s *Store) GetTraceByID(traceID string) ([]SpanSummary, error)
  • func (s *Store) GetTraceIDs(service string, limit int) ([]string, error)
  • func (s *Store) ListServices() ([]ServiceSummary, error)
  • func (s *Store) WriteResourceSpans(rs *tracev1.ResourceSpans) error

Constants

const DefaultRetentionDays = 60

Types

type MonthInfo

type MonthInfo struct {
	Month     string
	SpanCount int64
}

MonthInfo holds stats for one month sub-bucket.

type ServiceInfo

type ServiceInfo struct {
	Name   string
	Months []MonthInfo
}

ServiceInfo holds stats for one service bucket and its month sub-buckets.

type ServiceSummary

type ServiceSummary struct {
	Name        string
	TraceCount  int64
	SpanCount   int64
	LastUpdated time.Time
}

ServiceSummary holds aggregate statistics for a single service.

type SpanSummary

type SpanSummary struct {
	TraceID      string
	SpanID       string
	ParentSpanID string
	Name         string
	Month        string
	StartTime    time.Time
	EndTime      time.Time
	Status       int32
	SpanProto    []byte // serialized opentelemetry.proto.trace.v1.Span
}

SpanSummary holds the key fields of a stored span for display purposes.

type Store

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

Store wraps a bbolt database for trace storage.

func Open

func Open(path string, retentionDays int) (*Store, error)

Open opens or creates the bbolt database at the given path. retentionDays controls how long trace data is kept; 0 uses the default (60 days).

func (*Store) BucketStats

func (s *Store) BucketStats() ([]ServiceInfo, error)

BucketStats returns the list of service buckets and their month sub-buckets together with the span count for each month.

func (*Store) Cleanup

func (s *Store) Cleanup() error

Cleanup removes month buckets older than the configured retention period, and removes any service bucket that becomes empty as a result.

func (*Store) Close

func (s *Store) Close() error

Close closes the database.

func (*Store) DeleteService

func (s *Store) DeleteService(service string) error

DeleteService removes the top-level bucket for the named service and all of its data. It is a no-op if the service does not exist.

func (*Store) GetSpanTree

func (s *Store) GetSpanTree(spanID []byte) (traceID string, spans []SpanSummary, err error)

GetSpanTree finds the span with the given span_id, then returns all spans that share its trace_id within a ±2-minute window around its start time. The span_id must be the raw 8-byte value (not hex). Returns an empty traceID and nil slice if the span is not found.

func (*Store) GetSpans

func (s *Store) GetSpans(service string, limit int) ([]SpanSummary, error)

GetSpans returns the last `limit` spans for the named service, ordered most recent first. It walks month buckets in reverse chronological order and uses a reverse cursor within each bucket (keys are ULID-prefixed so they sort by time). If limit <= 0 it defaults to 50.

func (*Store) GetTraceByID

func (s *Store) GetTraceByID(traceID string) ([]SpanSummary, error)

GetTraceByID returns all spans whose trace_id matches the given hex string, scanning every service and month bucket. This is a full table scan; use it for interactive trace lookups where completeness matters over speed.

func (*Store) GetTraceIDs

func (s *Store) GetTraceIDs(service string, limit int) ([]string, error)

GetTraceIDs returns the last `limit` unique trace IDs for the named service, ordered most recent first. Scans spans newest-first across month buckets and deduplicates by trace ID. If limit <= 0 it defaults to 100.

func (*Store) ListServices

func (s *Store) ListServices() ([]ServiceSummary, error)

ListServices returns one ServiceSummary per stored service. For each service it counts total spans and distinct trace IDs by scanning all month buckets, and extracts the exact timestamp of the most recent span from the ULID key prefix of the last entry in the newest month bucket.

func (*Store) WriteResourceSpans

func (s *Store) WriteResourceSpans(rs *tracev1.ResourceSpans) error

WriteResourceSpans writes each span in rs as a separate DB entry. Bucket hierarchy: service-name -> YYYY-MM -> (ULID || SpanId) key -> compressed protobuf. The key is 24 bytes: 16-byte ULID of the span start time followed by the 8-byte span_id.