PSR-3 logging middleware for thesis/grpc: client and server interceptors that log every unary and streaming RPC with its method, type, status code and duration, at a log level derived from the gRPC status.

• Installation
• Usage
• Configuration
• Log levels
• Log fields
• How it works

composer require thesis/grpc-logging

There are two interceptors — one per side. Each implements both the unary and stream contracts of its side, so a single instance covers all RPC types.

use Psr\Log\LoggerInterface;
use Thesis\Grpc\Client;
use Thesis\Grpc\Logging;
use Thesis\Grpc\Server;

/** @var LoggerInterface $logger */
$config = new Logging\Config($logger);

// Client
$client = new Client\Builder()
    ->withUnaryInterceptors(new Logging\ClientInterceptor($config))
    ->withStreamInterceptors(new Logging\ClientInterceptor($config))
    ->build();

// Server
$server = new Server\Builder()
    ->withUnaryInterceptors(new Logging\ServerInterceptor($config))
    ->withStreamInterceptors(new Logging\ServerInterceptor($config))
    ->build();

The $logger is any PSR-3 logger (Monolog, etc.).

Logging\Config is an immutable dto:

use Thesis\Grpc\Logging\Config;
use Thesis\Grpc\Logging\Event;

new Config(
    logger: $logger,                          // required PSR-3 logger
    levels: new Logging\DefaultLevels(),      // gRPC status → PSR-3 level
    events: [Event::Start, Event::Finish],    // which points of the call to log
);

Event cases:

• Start — a started call record when the call begins.
• Finish — a finished call record with the status and duration when it ends.
• PayloadSent / PayloadReceived — a record for each message, named by role and direction: the client logs request sent / response received, the server response sent / request received, with the message object under grpc.request.content / grpc.response.content. Off by default.

To log only completed calls, pass events: [Event::Finish]. To also log message payloads (verbose, and potentially sensitive), add Event::PayloadSent / Event::PayloadReceived.

The finish record's level is derived from the call's gRPC status by a Levels implementation. DefaultLevels mirrors the grpc-ecosystem mapping — client-caused and expected statuses stay informational, transient ones warn, and genuine server faults are errors:

Provide your own by implementing Levels:

use Google\Rpc\Code;
use Psr\Log\LogLevel;
use Thesis\Grpc\Logging\Levels;

final class QuietLevels implements Levels
{
    public function level(Code $code): string
    {
        return $code === Code::OK ? LogLevel::DEBUG : LogLevel::WARNING;
    }
}

The start record is emitted at the OK level.

Each record carries a structured PSR-3 context:

Record messages are started call, finished call, and — for payload records — request sent, response sent, request received and response received.

• Unary calls are logged around the invocation: a start record (if enabled), then a finish record carrying the status and duration — OK on success, or the failure's status (an InvokeError's code, CANCELLED for a cancellation, UNKNOWN otherwise) before the error is rethrown.
• Server streams are logged the same way: the interceptor wraps the (blocking) handler call, so the finish record is written when the handler returns or throws.
• Client streams return before the RPC completes, so the interceptor logs the start immediately and wraps the stream in a decorator that completes the span at the terminal event, chosen by the RPC's cardinality (Invoke::$type), the way Go's grpc-middleware keys off the stream descriptor:
  • a single-response call (unary-over-stream, client streaming) terminates on its sole receive() — success is the finish (OK), a throw is the failure;
  • a server stream terminates on iteration — the iterator completing is the success, it throwing is the failure. (receive() has no clean end-of-stream — it throws even on success — so a server stream drained via raw receive() calls logs its messages but not a finish record.)
• Payload logging, when enabled, records every message. Unary payloads are logged inline (the request and response are right there). Streaming payloads are logged by the stream decorators as messages flow — the client decorator is always in place, and the server stream is wrapped only when a payload event is enabled, so the common lifecycle-only path stays decorator-free.