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 CgroupMemoryUsageRatio() (ratio float64, ok bool)
- func DBOperationAttr(op string) attribute.KeyValue
- func DBRowCountAttr(count int) attribute.KeyValue
- func DBTableAttr(table string) attribute.KeyValue
- func GetMeter() metric.Meter
- func GetTracer() trace.Tracer
- func GlobalOTLPHTTPEndpoint() string
- func HistoryEntryCountAttr(count int) attribute.KeyValue
- func IsGloballyEnabled() bool
- 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 StartLinkedBackgroundSpan(ctx context.Context, name string) (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
- func SubprocessArgCountAttr(n int) attribute.KeyValue
- func SubprocessCommandAttr(cmd string) attribute.KeyValue
- type Config
- type Provider
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" // Subprocess attributes (executor/safeexec instrumentation) AttrSubprocessCommand = "subprocess.command" AttrSubprocessArgCount = "subprocess.arg_count" )
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" // DefaultOTLPHTTPEndpoint is the default OTLP/HTTP collector endpoint used // to relay browser-originated spans/metrics (see OTLPHTTPEndpoint below). DefaultOTLPHTTPEndpoint = "http://localhost:4318" )
Variables ¶
This section is empty.
Functions ¶
func AddEvent ¶
func AddEvent(ctx context.Context, name string, attrs ...trace.EventOption)
AddEvent adds an event to the current span
func CgroupMemoryUsageRatio ¶ added in v1.49.0
CgroupMemoryUsageRatio returns this process's cgroup memory.current as a fraction of memory.high (e.g. 0.9 = 90% of the soft throttle ceiling) — the same figures registerCgroupMemoryMetrics exports as cgroup_memory_current_bytes/cgroup_memory_high_bytes, exposed directly for in-process consumers (server/services.MemoryPressureNotifier) that need a live reading without querying back through the metrics pipeline. ok is false if memory.high is unset ("max") or either file can't be read.
func DBOperationAttr ¶
DBOperationAttr creates an attribute for database operation
func DBRowCountAttr ¶
DBRowCountAttr creates an attribute for database row count
func DBTableAttr ¶
DBTableAttr creates an attribute for database table
func GetMeter ¶ added in v1.39.0
GetMeter returns the global meter (convenience function). Safe to call before Initialize (returns a no-op meter) — packages registering observable instruments at init/construction time don't need to wait for telemetry.Initialize to run first.
func GlobalOTLPHTTPEndpoint ¶ added in v1.52.0
func GlobalOTLPHTTPEndpoint() string
GlobalOTLPHTTPEndpoint returns the configured OTLP/HTTP collector endpoint (see Config.OTLPHTTPEndpoint), or "" before Initialize has run.
func HistoryEntryCountAttr ¶
HistoryEntryCountAttr creates an attribute for history entry count
func IsGloballyEnabled ¶ added in v1.52.0
func IsGloballyEnabled() bool
IsGloballyEnabled reports whether Initialize has run with tracing/metrics enabled. Safe to call before Initialize (returns false). Used by server/handlers.OtelProxyHandler's registration to decide whether to expose the browser-trace relay endpoints at all.
func RecordError ¶
func RecordError(ctx context.Context, err error, opts ...trace.EventOption)
RecordError records an error on the current span
func ReviewQueueSizeAttr ¶
ReviewQueueSizeAttr creates an attribute for review queue size
func SearchDurationMsAttr ¶
SearchDurationMsAttr creates an attribute for search duration in milliseconds
func SearchQueryAttr ¶
SearchQueryAttr creates an attribute for search query
func SearchResultCountAttr ¶
SearchResultCountAttr creates an attribute for search result count
func SessionIDAttr ¶
SessionIDAttr creates an attribute for session ID
func SessionStatusAttr ¶
SessionStatusAttr creates an attribute for session status
func SessionTitleAttr ¶
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 ¶
SpanFromContext returns the current span from context
func StartLinkedBackgroundSpan ¶ added in v1.51.0
StartLinkedBackgroundSpan starts a new-root span for work that outlives its triggering request (e.g. a goroutine started from an RPC handler that returns before the goroutine finishes), linked back to ctx's existing span (if any) for correlation. See ADR-003 (project_plans/async-session-creation/decisions/ADR-003-linked-root-span-for-background-goroutine.md): a plain child span risks rendering as a late/orphaned addition once some APM backends (this repo's target is Datadog) consider the trace complete after its root span closes. Any future "goroutine outlives its request" instrumentation should use this helper rather than hand-rolling trace.WithNewRoot()/trace.WithLinks() at each call site.
GetTracer() already returns a working no-op tracer when telemetry is disabled, so this is safe to call unconditionally — it never panics and always returns a usable (context, span) pair.
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 ¶
StorageCountAttr creates an attribute for storage item count
func StorageOperationAttr ¶
StorageOperationAttr creates an attribute for storage operation type
func SubprocessArgCountAttr ¶ added in v1.49.0
SubprocessArgCountAttr creates an attribute for the subprocess argument count
func SubprocessCommandAttr ¶ added in v1.49.0
SubprocessCommandAttr creates an attribute for the subprocess command name
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
// OTLPHTTPEndpoint is the OTLP/HTTP collector endpoint (e.g.,
// "http://localhost:4318") that server/handlers.OtelProxyHandler relays
// browser-originated OTLP export requests to. Kept separate from
// OTLPEndpoint because the Go SDK exports over gRPC while browsers export
// over HTTP — same collector, different protocol/port.
OTLPHTTPEndpoint 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 ¶
Initialize sets up OpenTelemetry with the given configuration. If telemetry is disabled, it returns a no-op provider.
func (*Provider) Meter ¶ added in v1.39.0
Meter returns the configured meter for creating instruments (counters, histograms, observable gauges). A no-op meter when telemetry is disabled — instruments still work, they just don't export anywhere.
Source Files