telemetry

Documentation

Overview

Package telemetry provides OpenTelemetry instrumentation for stapler-squad.

Package telemetry provides OpenTelemetry instrumentation for stapler-squad. It initializes tracing and metrics exporters for APM integration (Datadog, etc.).

Index

• Constants
• func AddEvent(ctx context.Context, name string, attrs ...trace.EventOption)
• func DBOperationAttr(op string) attribute.KeyValue
• func DBRowCountAttr(count int) attribute.KeyValue
• func DBTableAttr(table string) attribute.KeyValue
• func GetTracer() trace.Tracer
• func HistoryEntryCountAttr(count int) attribute.KeyValue
• func RecordError(ctx context.Context, err error, opts ...trace.EventOption)
• func ReviewQueueSizeAttr(size int) attribute.KeyValue
• func SearchDurationMsAttr(durationMs int64) attribute.KeyValue
• func SearchQueryAttr(query string) attribute.KeyValue
• func SearchResultCountAttr(count int) attribute.KeyValue
• func SessionIDAttr(id string) attribute.KeyValue
• func SessionStatusAttr(status string) attribute.KeyValue
• func SessionTitleAttr(title string) attribute.KeyValue
• func SetAttributes(ctx context.Context, attrs ...trace.EventOption)
• func SpanFromContext(ctx context.Context) trace.Span
• func StartSpan(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
• func StorageCountAttr(count int) attribute.KeyValue
• func StorageOperationAttr(op string) attribute.KeyValue
• type Config
  • func DefaultConfig() Config
• type Provider
  • func Initialize(ctx context.Context, cfg Config) (*Provider, error)
  • func (p *Provider) IsEnabled() bool
  • func (p *Provider) Shutdown(ctx context.Context) error
  • func (p *Provider) Tracer() trace.Tracer

Constants

const (
	// Session attributes
	AttrSessionID       = "session.id"
	AttrSessionTitle    = "session.title"
	AttrSessionStatus   = "session.status"
	AttrSessionProgram  = "session.program"
	AttrSessionCategory = "session.category"

	// History attributes
	AttrHistoryProject      = "history.project"
	AttrHistorySessionID    = "history.session_id"
	AttrHistoryEntryCount   = "history.entry_count"
	AttrHistoryMessageCount = "history.message_count"

	// Search attributes
	AttrSearchQuery       = "search.query"
	AttrSearchResultCount = "search.result_count"
	AttrSearchDurationMs  = "search.duration_ms"
	AttrSearchIndexSize   = "search.index_size"

	// Storage attributes
	AttrStorageOperation  = "storage.operation"
	AttrStorageCount      = "storage.count"
	AttrStorageDurationMs = "storage.duration_ms"

	// Database attributes (SQLite)
	AttrDBOperation = "db.operation"
	AttrDBTable     = "db.table"
	AttrDBRowCount  = "db.row_count"

	// Review queue attributes
	AttrReviewQueueSize     = "review_queue.size"
	AttrReviewQueuePriority = "review_queue.priority"
	AttrReviewQueueReason   = "review_queue.reason"
)

Semantic attribute keys for stapler-squad operations

const (
	// ServiceName is the name used in telemetry traces
	ServiceName = "stapler-squad"

	// DefaultOTLPEndpoint is the default endpoint for OTLP gRPC (Datadog Agent)
	DefaultOTLPEndpoint = "localhost:4317"
)

Functions

func AddEvent

func AddEvent(ctx context.Context, name string, attrs ...trace.EventOption)

AddEvent adds an event to the current span

func DBOperationAttr

func DBOperationAttr(op string) attribute.KeyValue

DBOperationAttr creates an attribute for database operation

func DBRowCountAttr

func DBRowCountAttr(count int) attribute.KeyValue

DBRowCountAttr creates an attribute for database row count

func DBTableAttr

func DBTableAttr(table string) attribute.KeyValue

DBTableAttr creates an attribute for database table

func GetTracer

func GetTracer() trace.Tracer

GetTracer returns the global tracer (convenience function)

func HistoryEntryCountAttr

func HistoryEntryCountAttr(count int) attribute.KeyValue

HistoryEntryCountAttr creates an attribute for history entry count

func RecordError

func RecordError(ctx context.Context, err error, opts ...trace.EventOption)

RecordError records an error on the current span

func ReviewQueueSizeAttr

func ReviewQueueSizeAttr(size int) attribute.KeyValue

ReviewQueueSizeAttr creates an attribute for review queue size

func SearchDurationMsAttr

func SearchDurationMsAttr(durationMs int64) attribute.KeyValue

SearchDurationMsAttr creates an attribute for search duration in milliseconds

func SearchQueryAttr

func SearchQueryAttr(query string) attribute.KeyValue

SearchQueryAttr creates an attribute for search query

func SearchResultCountAttr

func SearchResultCountAttr(count int) attribute.KeyValue

SearchResultCountAttr creates an attribute for search result count

func SessionIDAttr

func SessionIDAttr(id string) attribute.KeyValue

SessionIDAttr creates an attribute for session ID

func SessionStatusAttr

func SessionStatusAttr(status string) attribute.KeyValue

SessionStatusAttr creates an attribute for session status

func SessionTitleAttr

func SessionTitleAttr(title string) attribute.KeyValue

SessionTitleAttr creates an attribute for session title

func SetAttributes

func SetAttributes(ctx context.Context, attrs ...trace.EventOption)

SetAttributes sets attributes on the current span

func SpanFromContext

func SpanFromContext(ctx context.Context) trace.Span

SpanFromContext returns the current span from context

func StartSpan

func StartSpan(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)

StartSpan creates a new span with the given name and options

func StorageCountAttr

func StorageCountAttr(count int) attribute.KeyValue

StorageCountAttr creates an attribute for storage item count

func StorageOperationAttr

func StorageOperationAttr(op string) attribute.KeyValue

StorageOperationAttr creates an attribute for storage operation type

Types

type Config

type Config struct {
	// Enabled controls whether telemetry is active
	Enabled bool

	// OTLPEndpoint is the gRPC endpoint for OTLP exporter (e.g., "localhost:4317")
	OTLPEndpoint string

	// ServiceVersion is the version of the service
	ServiceVersion string

	// Environment is the deployment environment (e.g., "development", "production")
	Environment string

	// SampleRate is the trace sampling rate (0.0 to 1.0)
	SampleRate float64
}

Config holds telemetry configuration

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults

type Provider

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

Provider holds the initialized telemetry providers

func Initialize

func Initialize(ctx context.Context, cfg Config) (*Provider, error)

Initialize sets up OpenTelemetry with the given configuration. If telemetry is disabled, it returns a no-op provider.

func (*Provider) IsEnabled

func (p *Provider) IsEnabled() bool

IsEnabled returns whether telemetry is enabled

func (*Provider) Shutdown

func (p *Provider) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the telemetry provider

func (*Provider) Tracer

func (p *Provider) Tracer() trace.Tracer

Tracer returns the configured tracer for creating spans