Documentation
¶
Overview ¶
Package observability wires OpenTelemetry traces for the identity server. Deployers point the server at any OTLP-compatible collector via GATEWAY_OTEL_*; when disabled, the no-op tracer provider is installed and the server pays no per-request cost.
Index ¶
- Constants
- func LoggerFor(ctx context.Context, base *zap.Logger) *zap.Logger
- func Setup(ctx context.Context, cfg Config) (shutdown func(context.Context) error, err error)
- func StartClient(ctx context.Context, name string, attrs ...attribute.KeyValue) (context.Context, func(error))
- func TraceIDFromContext(ctx context.Context) string
- func Tracer() trace.Tracer
- func WrapIDVProvider(p idv.Provider) idv.Provider
- func WrapMailer(t email.Transport) email.Transport
- func WrapOAuthExchanger(provider string, e oauth.Exchanger) oauth.Exchanger
- type Config
- type TracedExchanger
- type TracedIDVProvider
- type TracedMailer
Constants ¶
const ServiceName = "identity"
ServiceName is the otel resource attribute every span carries.
const TraceIDLogField = "trace_id"
TraceIDLogField is the zap field name carried on every log line emitted via LoggerFor(ctx, ...). Deployers searching their log backend for a specific trace pivot on this key regardless of the backend's structured-log conventions.
const TracerName = "github.com/elloloop/identity"
TracerName is the instrumentation name carried on every outbound span emitted by this server.
Variables ¶
This section is empty.
Functions ¶
func LoggerFor ¶
LoggerFor returns base with the active trace id from ctx attached as a structured field. If no span is recording (e.g. OTel disabled or caller serves a request that bypassed instrumentation) the original logger is returned unchanged. This avoids polluting log lines with the well-known all-zeros trace id.
func Setup ¶
Setup installs the global tracer provider and propagators. When cfg.Enabled is false it leaves OTel's no-op default in place and returns a no-op shutdown — the hot path then incurs only the dispatch through the no-op tracer. The returned shutdown must be called during graceful termination; it flushes pending spans up to 5 s before forcing the exporter closed.
Setup fails fast when cfg.Enabled is true but cfg.Endpoint is empty so a misconfigured deploy crashes at boot rather than silently dropping traces.
func StartClient ¶
func StartClient(ctx context.Context, name string, attrs ...attribute.KeyValue) (context.Context, func(error))
StartClient opens a client-kind span for an outbound call. The returned end function records the error (if non-nil) on the span and calls span.End() — callers use it as:
ctx, end := observability.StartClient(ctx, "db.GetUser",
attribute.String("db.tenant", tenantID))
defer func() { end(err) }()
When OTel is disabled the global no-op tracer is in effect and this allocates only the (very small) no-op Span struct.
func TraceIDFromContext ¶
TraceIDFromContext returns the active trace id from ctx as a hex string, or "" if the context carries no recording span. Callers embedding the id into non-zap structures (audit details, response headers) use this to avoid pulling in the otel/trace package directly.
func Tracer ¶
Tracer returns the named tracer. Callers should not cache the returned trace.Tracer across the global TracerProvider being replaced (currently it isn't, after Setup runs once at boot).
func WrapIDVProvider ¶
WrapIDVProvider returns p wrapped in client-kind spans. Returns nil when p is nil so callers can construct optional providers without special-casing.
func WrapMailer ¶
WrapMailer returns t wrapped in client-kind spans for Send.
Types ¶
type Config ¶
type Config struct {
Enabled bool
Endpoint string
Protocol string // "grpc" or "http"
SampleRatio float64
DeploymentEnv string
ServiceVersion string
// Insecure skips TLS on the OTLP transport. Defaults to true since
// most collectors run inside the cluster network; deployers who
// front a TLS-only collector will need a follow-up knob.
Insecure bool
}
Config controls how the tracer provider is constructed. It mirrors the GATEWAY_OTEL_* env knobs; see config.Config for documentation.
func FromAppConfig ¶
FromAppConfig translates a *config.Config into the observability Config used by Setup.
type TracedExchanger ¶
type TracedExchanger struct {
// contains filtered or unexported fields
}
TracedExchanger wraps oauth.Exchanger with a client-kind span for the outbound token-endpoint POST. When the inner value also satisfies oauth.Authorizer (the production Google / Microsoft / GitHub implementations do), the wrapper exposes the same surface so the service-layer's `exchanger.(oauth.Authorizer)` assertion keeps working.
func (*TracedExchanger) Exchange ¶
func (t *TracedExchanger) Exchange(ctx context.Context, params oauth.ExchangeParams) (*oauth.Identity, error)
type TracedIDVProvider ¶
type TracedIDVProvider struct {
// contains filtered or unexported fields
}
TracedIDVProvider wraps an idv.Provider with client-kind spans so outbound BeginVerification / GetVerification calls show up in a distributed trace.
func (*TracedIDVProvider) BeginVerification ¶
func (*TracedIDVProvider) GetVerification ¶
func (t *TracedIDVProvider) GetVerification(ctx context.Context, providerSessionID string) (*idv.StatusResult, error)
func (*TracedIDVProvider) Name ¶
func (t *TracedIDVProvider) Name() string
type TracedMailer ¶
type TracedMailer struct {
// contains filtered or unexported fields
}
TracedMailer wraps an email.Transport with client-kind spans. The span is tagged with subject but not the recipient — addresses are PII and we already redact them in the existing email logger.
Source Files