Documentation
¶
Index ¶
- func LoggerStreamInterceptor(srv interface{}, stream grpc.ServerStream, info *grpc.StreamServerInfo, ...) error
- func LoggerUnaryInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, ...) (interface{}, error)
- func NewLoggerInterceptors(z *data.ZapLog, opts ...Option) (grpc.UnaryServerInterceptor, grpc.StreamServerInterceptor)
- type Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LoggerStreamInterceptor ¶
func LoggerStreamInterceptor(srv interface{}, stream grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error
LoggerStreamInterceptor is the legacy stream interceptor preserved for backward compatibility. See LoggerUnaryInterceptor for the rationale — new code should prefer NewLoggerInterceptors.
func LoggerUnaryInterceptor ¶
func LoggerUnaryInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error)
LoggerUnaryInterceptor is the legacy unary interceptor preserved for backward compatibility. It logs method + duration + status to the standard library log package without structured fields and without any metadata extraction. New code should prefer NewLoggerInterceptors.
This function never panics, never blocks, and never mutates the request/response. It is safe to wire into an interceptor chain regardless of context.
func NewLoggerInterceptors ¶ added in v1.8.0
func NewLoggerInterceptors(z *data.ZapLog, opts ...Option) (grpc.UnaryServerInterceptor, grpc.StreamServerInterceptor)
Types ¶
type Option ¶ added in v1.8.0
type Option func(*loggerOptions)
Option configures the structured logger interceptors returned by NewLoggerInterceptors. Options follow the standard functional-options idiom — pass any number; later options override earlier ones.
func WithLogMetadata ¶ added in v1.8.0
WithLogMetadata controls whether incoming gRPC metadata is included as a structured field on each log entry. Defaults to false because metadata is a common PII source. When enabled, sensitive headers are still redacted via the denylist.
func WithLogPeer ¶ added in v1.8.0
WithLogPeer controls whether the peer address (from grpc/peer) is included on each log entry.
Default: false. SP-010 pass-5 A4-F1 (2026-04-15) flipped this from true → false because client IPs are personal data under GDPR, CCPA, and UK-DPA; the previous default silently pulled every deployment of this package into a data-protection amendment that nobody signed up for. A package named "PII-aware logger" should not require opt-out to be PII-safe.
Set WithLogPeer(true) explicitly in environments where peer logging is required (typically internal-only backends, compliance-audit pipelines, or non-regulated B2B deployments). Document the decision in your service's data-retention policy when you do.
Breaking change notice: services that previously relied on the implicit true default will need to add WithLogPeer(true) to their interceptor construction when upgrading past v1.8.2. Grep for NewLoggerInterceptors at upgrade time.
func WithSampleRate ¶ added in v1.8.2
WithSampleRate caps the number of log emissions per second using a token bucket. Values <= 0 mean unlimited (the default, which preserves backward-compatible behavior for every consumer that does not opt in). Dropped emissions are silently discarded — the RPC still completes normally, only the access log line is skipped.
Motivation — SP-010 pass-5 A4-F3 (2026-04-15): a hot-path emitter with no upper bound becomes the largest line item on the CloudWatch ingest bill the moment something misbehaves upstream. A 5K RPS scanner storm or a panic loop in a downstream service produces 5K lines/s through Errorw, and Zap itself does not throttle. The metrics package learned the same operational invariant via M1-001; applying it to the logger closes the symmetry gap. Default unlimited was chosen over error-only throttling because success-path volume can spike just as hard (retry storms, client reconnect floods) and a single option that caps both is simpler to reason about than two separate throttles.
Burst is set equal to perSecondCap so that short bursts are absorbed cleanly while the steady-state rate enforces the cap. A cap of 100 means "up to 100 tokens available instantaneously, refilling at 100 tokens/second."
Lifecycle: each NewLoggerInterceptors call receives its own limiter — limiters are NOT shared across services, so a 100 rps cap applied to two services yields up to 200 rps combined. This matches the per-interceptor-instance lifecycle of the other options and avoids cross-service interference. The same limiter is shared by the unary and stream interceptor pair returned from a single constructor call (both sides of the pair receive cfg by closure), so the cap applies to the combined unary+stream emission rate, which is the natural accounting unit for a single logical service.
Concurrency: rate.Limiter.Allow() is goroutine-safe via its internal mutex; no additional synchronization is required.
func WithSensitiveHeaders ¶ added in v1.8.0
WithSensitiveHeaders extends the metadata redaction denylist beyond the built-in set (authorization, cookie, x-api-key, ...). Header names are matched case-insensitively. Use this to redact tenant-specific or product-specific secrets that the default list does not know about.
Source Files