rpclog

README

RPC Logger

A structured logging interceptor for Connect RPC with support for both unary and streaming RPCs.

Features

• Structured logging using slog.Logger
• Comprehensive RPC metadata including service, method, duration, and peer info
• Error classification with automatic log level determination
• Contextual logging with request-scoped loggers
• Authentication context logging when available
• Support for all RPC types:
  • Unary RPCs
  • Server-side streaming
  • Client-side streaming

Installation

go get github.com/mdigger/rpclog

Usage

Basic Setup

package main

import (
	"log/slog"
	"github.com/mdigger/rpclog"
	"connectrpc.com/connect"
)

func main() {
	// Create a new logger
	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
	
	// Create the interceptor
	loggingInterceptor := rpclog.New(logger)
	
	// Add to your interceptors
	interceptors := connect.WithInterceptors(loggingInterceptor)
	
	// Use with your Connect server or client
	// ...
}

Logged Information

For each RPC, the logger captures:

• Basic RPC info:

  • service: The service name
  • method: The method being called
  • type: The stream type (unary, client, server, bidi)
  • duration: Call duration

• Network info:

  • protocol: Network protocol used
  • addr: Peer address

• Error info (when applicable):

  • code: Connect error code
  • error: Error message

• Auth info (when available):

  • auth: Authentication context

Retrieving the Context Logger

You can retrieve the request-scoped logger from the context:

logger := rpclog.Get(ctx)
logger.Info("using the request-scoped logger")

Example Output

{
  "time": "2023-10-01T12:00:00Z",
  "level": "INFO",
  "msg": "rpc call",
  "service": "greeter.v1",
  "method": "SayHello",
  "type": "Unary",
  "protocol": "grpc",
  "addr": "127.0.0.1:12345",
  "duration": 0.012345
}

{
  "time": "2023-10-01T12:00:01Z",
  "level": "ERROR",
  "msg": "rpc call",
  "service": "greeter.v1",
  "method": "SayHello",
  "type": "Unary",
  "protocol": "grpc",
  "addr": "127.0.0.1:12345",
  "duration": 0.012345,
  "code": 13,
  "error": "service unavailable"
}

Configuration

The logger uses slog.Level for log levels, automatically determined by:

• ERROR: For internal server errors (CodeInternal and above)
• WARN: For unimplemented methods
• INFO: For successful calls and other errors

Best Practices

1. Use structured logging handlers (JSON or logfmt) for production
2. Add additional context using rpclog.Get(ctx)
3. Combine with other interceptors like metrics and tracing
4. Set appropriate log levels on your base logger

Documentation

Overview

Package rpclog provides logging support for Connect RPCs, including both unary and streaming RPCs. It implements connect.Interceptor to log RPC details such as service, method, duration, peer information, and error codes. The package supports structured logging using slog.Logger.

Index

• func Get(ctx context.Context) *slog.Logger
• type Interceptor
  • func New(log *slog.Logger) *Interceptor
  • func (l *Interceptor) WrapStreamingClient(next connect.StreamingClientFunc) connect.StreamingClientFunc
  • func (l *Interceptor) WrapStreamingHandler(next connect.StreamingHandlerFunc) connect.StreamingHandlerFunc
  • func (l *Interceptor) WrapUnary(next connect.UnaryFunc) connect.UnaryFunc

Functions

func Get

func Get(ctx context.Context) *slog.Logger

Get retrieves the logger from the context. If no logger is found in the context, it returns the default slog.Logger.

Types

type Interceptor

type Interceptor struct {
	// contains filtered or unexported fields
}

Interceptor implements the connect.Interceptor interface to provide logging support for RPCs.

func New

func New(log *slog.Logger) *Interceptor

New creates and returns a new Connect RPC logger instance with the provided slog.Logger. The logger will be used as the base for all RPC logging.

func (*Interceptor) WrapStreamingClient

func (l *Interceptor) WrapStreamingClient(
	next connect.StreamingClientFunc,
) connect.StreamingClientFunc

WrapStreamingClient implements the connect.Interceptor interface for client-side streaming RPCs. It wraps the next handler to log: - Start and end of the client stream - Duration of the stream - Service and method names

func (*Interceptor) WrapStreamingHandler

func (l *Interceptor) WrapStreamingHandler(
	next connect.StreamingHandlerFunc,
) connect.StreamingHandlerFunc

WrapStreamingHandler implements the connect.Interceptor interface for server-side streaming RPCs. It wraps the next handler to log: - Start and end of the stream - Duration of the stream - Service and method names - Peer information - Error information (if any)

func (*Interceptor) WrapUnary

func (l *Interceptor) WrapUnary(next connect.UnaryFunc) connect.UnaryFunc

WrapUnary implements the connect.Interceptor interface for unary RPCs. It wraps the next handler to log: - Start and end of the RPC call - Duration of the call - Service and method names - Peer information (protocol and address) - Authentication details (if available) - Error information (if any)