observability

package
v1.6.2 Latest Latest
Warning

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

 Go to latest Published: May 13, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

Documentation

Overview

Package observability provides hooks for metrics, tracing, and logging.

This package enables optional instrumentation without adding hard dependencies on specific observability backends. Consumers can register hooks at startup to receive events about pipeline execution, cache operations, and API calls.

Architecture

The package uses a simple hooks pattern:

  • Define hook interfaces for different event categories
  • Provide no-op default implementations
  • Allow registration of custom implementations at startup

This approach:

  • Avoids import cycles (hooks are registered by main, not by libraries)
  • Keeps the core library dependency-free from observability frameworks
  • Allows different backends (OpenTelemetry, Prometheus, DataDog, etc.)

Usage

Register hooks at application startup: 

func main() {
    observability.SetPipelineHooks(&myPipelineHooks{})
    observability.SetCacheHooks(&myCacheHooks{})
    // ... run application
}

Libraries call hooks to emit events: 

observability.Pipeline().OnParseStart(ctx, language, pkg)
// ... do parsing ...
observability.Pipeline().OnParseComplete(ctx, language, pkg, nodeCount, duration, err)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Reset 

func Reset()

Reset restores all hooks to their no-op defaults. This is primarily useful for testing.

func SetCacheHooks 

func SetCacheHooks(h CacheHooks)

SetCacheHooks registers custom cache hooks. This should be called once at application startup before any cache operations.

func SetHTTPHooks 

func SetHTTPHooks(h HTTPHooks)

SetHTTPHooks registers custom HTTP hooks. This should be called once at application startup before any HTTP operations.

func SetPipelineHooks 

func SetPipelineHooks(h PipelineHooks)

SetPipelineHooks registers custom pipeline hooks. This should be called once at application startup before any pipeline operations.

func SetRateLimitHooks 

func SetRateLimitHooks(h RateLimitHooks)

SetRateLimitHooks registers custom rate limit hooks. Unlike other hooks, this may be called per-command to install a progress view for the duration of an operation. Pass nil to restore the no-op default.

func SetResolverHooks 

func SetResolverHooks(h ResolverHooks)

SetResolverHooks registers custom resolver hooks. Unlike other hooks, this may be called per-command to install a progress view for the duration of a resolve operation. Pass nil to restore the no-op default.

func SetSecurityHooks 

func SetSecurityHooks(h SecurityHooks)

SetSecurityHooks registers custom security hooks. This should be called once at application startup before any security scanning.

func WithPipelineHooks 

func WithPipelineHooks(ctx context.Context, hooks PipelineHooks) context.Context

WithPipelineHooks returns a context with pipeline hooks attached. Use this for per-job hooks in concurrent server environments.

func WithResolverHooks 

func WithResolverHooks(ctx context.Context, hooks ResolverHooks) context.Context

WithResolverHooks returns a context with resolver hooks attached. Use this for per-job hooks in concurrent server environments. The hooks in context take precedence over global hooks.

Types

type CacheHooks 

type CacheHooks interface {
	// OnCacheHit records a cache hit.
	OnCacheHit(ctx context.Context, keyType string)

	// OnCacheMiss records a cache miss.
	OnCacheMiss(ctx context.Context, keyType string)

	// OnCacheSet records a cache write.
	OnCacheSet(ctx context.Context, keyType string, size int)
}

CacheHooks receives events from cache operations.

func Cache 

func Cache() CacheHooks

Cache returns the registered cache hooks.

type CircuitState 

type CircuitState string

CircuitState represents the state of a circuit breaker. 

const (
	// CircuitClosed is the normal operating state where requests are allowed.
	CircuitClosed CircuitState = "closed"
	// CircuitOpen is the state where requests are rejected to allow recovery.
	CircuitOpen CircuitState = "open"
	// CircuitHalfOpen is the testing state where one probe request is allowed.
	CircuitHalfOpen CircuitState = "half-open"
)

type HTTPHooks 

type HTTPHooks interface {
	// OnRequest records an outgoing HTTP request.
	OnRequest(ctx context.Context, method, host, path string)

	// OnResponse records an HTTP response.
	OnResponse(ctx context.Context, method, host, path string, statusCode int, duration time.Duration)

	// OnError records an HTTP error (network failure, timeout).
	OnError(ctx context.Context, method, host, path string, err error)
}

HTTPHooks receives events from HTTP client operations.

func HTTP 

func HTTP() HTTPHooks

HTTP returns the registered HTTP hooks.

type NoopCacheHooks 

type NoopCacheHooks struct{}

NoopCacheHooks is a no-op implementation of CacheHooks.

func (NoopCacheHooks) OnCacheHit 

func (NoopCacheHooks) OnCacheHit(context.Context, string)

func (NoopCacheHooks) OnCacheMiss 

func (NoopCacheHooks) OnCacheMiss(context.Context, string)

func (NoopCacheHooks) OnCacheSet 

func (NoopCacheHooks) OnCacheSet(context.Context, string, int)

type NoopHTTPHooks 

type NoopHTTPHooks struct{}

NoopHTTPHooks is a no-op implementation of HTTPHooks.

func (NoopHTTPHooks) OnError 

func (NoopHTTPHooks) OnError(context.Context, string, string, string, error)

func (NoopHTTPHooks) OnRequest 

func (NoopHTTPHooks) OnRequest(context.Context, string, string, string)

func (NoopHTTPHooks) OnResponse 

func (NoopHTTPHooks) OnResponse(context.Context, string, string, string, int, time.Duration)

type NoopPipelineHooks 

type NoopPipelineHooks struct{}

NoopPipelineHooks is a no-op implementation of PipelineHooks.

func (NoopPipelineHooks) OnLayoutComplete 

func (NoopPipelineHooks) OnLayoutComplete(context.Context, string, time.Duration, error)

func (NoopPipelineHooks) OnLayoutStart 

func (NoopPipelineHooks) OnLayoutStart(context.Context, string, int)

func (NoopPipelineHooks) OnOrderingComplete 

func (NoopPipelineHooks) OnOrderingComplete(context.Context, int, time.Duration)

func (NoopPipelineHooks) OnOrderingProgress 

func (NoopPipelineHooks) OnOrderingProgress(context.Context, int, int, int)

func (NoopPipelineHooks) OnOrderingStart 

func (NoopPipelineHooks) OnOrderingStart(context.Context, string, int)

func (NoopPipelineHooks) OnParseComplete 

func (NoopPipelineHooks) OnParseComplete(context.Context, string, string, int, time.Duration, error)

func (NoopPipelineHooks) OnParseStart 

func (NoopPipelineHooks) OnParseStart(context.Context, string, string)

func (NoopPipelineHooks) OnRenderComplete 

func (NoopPipelineHooks) OnRenderComplete(context.Context, []string, time.Duration, error)

func (NoopPipelineHooks) OnRenderStart 

func (NoopPipelineHooks) OnRenderStart(context.Context, []string)

type NoopRateLimitHooks 

type NoopRateLimitHooks struct{}

NoopRateLimitHooks is a no-op implementation of RateLimitHooks.

func (NoopRateLimitHooks) OnCircuitStateChange 

func (NoopRateLimitHooks) OnCircuitStateChange(context.Context, string, CircuitState, time.Time)

func (NoopRateLimitHooks) OnRateLimitHit 

func (NoopRateLimitHooks) OnRateLimitHit(context.Context, string, int)

func (NoopRateLimitHooks) OnRateLimitWait 

func (NoopRateLimitHooks) OnRateLimitWait(context.Context, string, time.Duration)

func (NoopRateLimitHooks) OnRetry 

func (NoopRateLimitHooks) OnRetry(context.Context, string, int, time.Duration)

type NoopResolverHooks 

type NoopResolverHooks struct{}

NoopResolverHooks is a no-op implementation of ResolverHooks.

func (NoopResolverHooks) OnEnrichComplete 

func (NoopResolverHooks) OnEnrichComplete(context.Context, string, int, error)

func (NoopResolverHooks) OnEnrichStart 

func (NoopResolverHooks) OnEnrichStart(context.Context, string, int)

func (NoopResolverHooks) OnFetchComplete 

func (NoopResolverHooks) OnFetchComplete(context.Context, string, int, int, error)

func (NoopResolverHooks) OnFetchStart 

func (NoopResolverHooks) OnFetchStart(context.Context, string, int)

func (NoopResolverHooks) OnProgress 

func (NoopResolverHooks) OnProgress(context.Context, int, int, int)

type NoopSecurityHooks 

type NoopSecurityHooks struct{}

NoopSecurityHooks is a no-op implementation of SecurityHooks.

func (NoopSecurityHooks) OnScanComplete 

func (NoopSecurityHooks) OnScanComplete(context.Context, string, int, time.Duration, error)

func (NoopSecurityHooks) OnScanStart 

func (NoopSecurityHooks) OnScanStart(context.Context, string, int)

type PipelineHooks 

type PipelineHooks interface {
	// Parse events
	OnParseStart(ctx context.Context, language, pkg string)
	OnParseComplete(ctx context.Context, language, pkg string, nodeCount int, duration time.Duration, err error)

	// Layout events
	OnLayoutStart(ctx context.Context, vizType string, nodeCount int)
	OnLayoutComplete(ctx context.Context, vizType string, duration time.Duration, err error)

	// Ordering events (during layout for tower visualization)
	OnOrderingStart(ctx context.Context, algorithm string, rowCount int)
	OnOrderingProgress(ctx context.Context, explored, pruned, bestCrossings int)
	OnOrderingComplete(ctx context.Context, crossings int, duration time.Duration)

	// Render events
	OnRenderStart(ctx context.Context, formats []string)
	OnRenderComplete(ctx context.Context, formats []string, duration time.Duration, err error)
}

PipelineHooks receives events from the visualization pipeline.

func Pipeline 

func Pipeline() PipelineHooks

Pipeline returns the registered pipeline hooks.

func PipelineFromContext 

func PipelineFromContext(ctx context.Context) PipelineHooks

PipelineFromContext returns pipeline hooks from context if set, otherwise returns the global pipeline hooks.

type RateLimitHooks 

type RateLimitHooks interface {
	// OnRateLimitWait records time spent waiting for rate limit tokens.
	OnRateLimitWait(ctx context.Context, registry string, waitDuration time.Duration)

	// OnRetry records a retry attempt with backoff.
	OnRetry(ctx context.Context, registry string, attempt int, backoffDuration time.Duration)

	// OnRateLimitHit records when an HTTP 429 rate limit response is received.
	OnRateLimitHit(ctx context.Context, registry string, retryAfterSeconds int)

	// OnCircuitStateChange records when a circuit breaker changes state.
	// The until parameter indicates when the circuit will transition (zero for immediate/unknown).
	OnCircuitStateChange(ctx context.Context, registry string, state CircuitState, until time.Time)
}

RateLimitHooks receives events from rate limiting operations.

func RateLimit 

func RateLimit() RateLimitHooks

RateLimit returns the registered rate limit hooks.

type ResolverHooks 

type ResolverHooks interface {
	// OnFetchStart is called when a worker begins fetching a package.
	OnFetchStart(ctx context.Context, pkg string, depth int)

	// OnFetchComplete is called when a worker finishes fetching a package.
	// depCount is the number of dependencies found (0 on error).
	OnFetchComplete(ctx context.Context, pkg string, depth int, depCount int, err error)

	// OnProgress is called after each result is collected with aggregate counters.
	OnProgress(ctx context.Context, resolved, pending, maxNodes int)

	// OnEnrichStart is called when batch enrichment begins (e.g., GitHub GraphQL).
	// provider identifies the enrichment source (e.g., "github").
	// count is the number of packages being enriched.
	OnEnrichStart(ctx context.Context, provider string, count int)

	// OnEnrichComplete is called when batch enrichment finishes.
	// enriched is the number of packages successfully enriched.
	OnEnrichComplete(ctx context.Context, provider string, enriched int, err error)
}

ResolverHooks receives events from the dependency resolver's worker pool. Implementations must be safe for concurrent use from multiple goroutines.

func Resolver 

func Resolver() ResolverHooks

Resolver returns the registered resolver hooks. If context-based hooks are set via WithResolverHooks, those take precedence over the global hooks, enabling per-request hooks for concurrent operations.

func ResolverFromContext 

func ResolverFromContext(ctx context.Context) ResolverHooks

ResolverFromContext returns resolver hooks from context if set, otherwise returns the global resolver hooks.

type SecurityHooks 

type SecurityHooks interface {
	// OnScanStart records the start of a vulnerability scan.
	OnScanStart(ctx context.Context, ecosystem string, depCount int)

	// OnScanComplete records the completion of a vulnerability scan.
	OnScanComplete(ctx context.Context, ecosystem string, findingCount int, duration time.Duration, err error)
}

SecurityHooks receives events from security scanning operations.

func Security 

func Security() SecurityHooks

Security returns the registered security hooks.

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.