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 CgroupMemoryUsageRatio() (ratio float64, ok bool)
- func GetMeter() metric.Meter
- func GetTracer() trace.Tracer
- func GlobalOTLPHTTPEndpoint() string
- func IsGloballyEnabled() bool
- 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 SubprocessArgCountAttr(n int) attribute.KeyValue
- func SubprocessCommandAttr(cmd string) attribute.KeyValue
- type Config
- type Provider
Constants ¶
const ( // Session attributes AttrSessionProgram = "session.program" AttrSessionCategory = "session.category" // History attributes AttrHistoryProject = "history.project" AttrHistorySessionID = "history.session_id" AttrHistoryMessageCount = "history.message_count" // Search attributes AttrSearchQuery = "search.query" AttrSearchIndexSize = "search.index_size" // Storage attributes AttrStorageDurationMs = "storage.duration_ms" // Review queue attributes 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 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 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 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 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 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