README
¶
orbit-observability
Go library: structured logging (slog), OpenTelemetry traces, health helpers, HTTP/gRPC middleware, and optional Sentry for Orbit-style services.
Part of the Manova / Orbit open toolkit.
Install
go get github.com/manovaspace/orbit-observability@latest
Local development (monorepo sibling):
replace github.com/manovaspace/orbit-observability => ../orbit-observability
Quick start
import observability "github.com/manovaspace/orbit-observability"
func main() {
if err := observability.Configure(observability.ConfigFromEnv("my-service", "0.1.0")); err != nil {
panic(err)
}
log := observability.Logger()
log.Info("started", "port", 8080)
mux := http.NewServeMux()
mux.HandleFunc("/healthz", func(w http.ResponseWriter, _ *http.Request) {
_ = json.NewEncoder(w).Encode(observability.Health())
})
http.ListenAndServe(":8080", observability.HTTPMiddleware(mux))
}
Set OTEL_EXPORTER_OTLP_ENDPOINT (for example localhost:10517) or pass Exporter: observability.ExporterOTLP for OTLP trace export.
Graceful shutdown:
observability.WaitForSignal(observability.ShutdownConfig{
GRPCServer: gs,
HTTPServer: healthServer,
})
Development
go test ./...
Contributing
See CONTRIBUTING.md. Security reports: SECURITY.md.
License
MIT — see LICENSE.
Documentation
¶
Index ¶
- func CaptureException(err error)
- func Configure(c Config) error
- func GRPCDialOptions() []grpc.DialOption
- func GRPCServerOptions() []grpc.ServerOption
- func HTTPMiddleware(next http.Handler) http.Handler
- func Health() map[string]string
- func HealthHandler() http.Handler
- func InternalAuthDialOption() grpc.DialOption
- func InternalAuthUnaryServerInterceptor() grpc.UnaryServerInterceptor
- func Logger() *slog.Logger
- func MarkNotLive()
- func Readiness() map[string]string
- func ReadinessHandler() http.Handler
- func SetReadiness(ok bool, message string)
- func Shutdown(ctx context.Context) error
- func Tracer() trace.Tracer
- func WaitForSignal(cfg ShutdownConfig)
- type Config
- type Exporter
- type ShutdownConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CaptureException ¶
func CaptureException(err error)
CaptureException sends an error to Sentry when configured.
func Configure ¶
Configure initializes logging, tracing, and optional Sentry. Safe to call once at startup.
func GRPCDialOptions ¶
func GRPCDialOptions() []grpc.DialOption
GRPCDialOptions returns gRPC client dial options with tracing.
func GRPCServerOptions ¶
func GRPCServerOptions() []grpc.ServerOption
GRPCServerOptions returns gRPC server options with tracing and internal token auth.
func HTTPMiddleware ¶
HTTPMiddleware wraps an http.Handler with W3C trace propagation.
func HealthHandler ¶
HealthHandler serves GET /healthz style liveness.
func InternalAuthDialOption ¶
func InternalAuthDialOption() grpc.DialOption
InternalAuthDialOption attaches ORBIT_INTERNAL_TOKEN to all outgoing RPCs.
func InternalAuthUnaryServerInterceptor ¶
func InternalAuthUnaryServerInterceptor() grpc.UnaryServerInterceptor
InternalAuthUnaryServerInterceptor rejects RPCs without a matching ORBIT_INTERNAL_TOKEN. When ORBIT_INTERNAL_TOKEN is empty and DEPLOYMENT_ENVIRONMENT=dev, auth is skipped.
func MarkNotLive ¶
func MarkNotLive()
MarkNotLive marks the process as not live (for graceful shutdown hooks).
func ReadinessHandler ¶
ReadinessHandler serves GET /readyz style readiness.
func SetReadiness ¶
SetReadiness marks readiness state for probes.
func WaitForSignal ¶
func WaitForSignal(cfg ShutdownConfig)
WaitForSignal blocks until SIGINT/SIGTERM, then drains servers and flushes telemetry.
Types ¶
type Config ¶
type Config struct {
ServiceName string
ServiceVersion string
Environment string
TenantID string
Exporter Exporter
OTLPEndpoint string
SentryDSN string
}
Config holds observability bootstrap options.
func ConfigFromEnv ¶
ConfigFromEnv builds Config from standard Orbit environment variables.
Source Files
Directories