Crate tonic_debug 

tonic-debug

A debugging and diagnostics middleware for tonic gRPC servers.

Overview

Debugging gRPC services built with tonic can be challenging — messages are binary-encoded protobufs, connection issues are opaque, and the standard logging often lacks the detail needed to quickly diagnose problems.

tonic-debug solves this by providing:

• Human-readable protobuf inspection — decodes protobuf wire format without needing .proto schemas, showing field numbers, types, and values.
• Connection lifecycle observability — tracks connection events (connect, disconnect, errors) with active/total counters via tower/hyper integration.
• Structured logging via tracing — all output goes through the tracing crate with structured fields for easy filtering and aggregation.
• Optional OpenTelemetry export — enable the opentelemetry feature to forward spans and attributes to your OTel collector.

Quick Start

use tonic_debug::DebugLayer;

// Add the debug layer to your tonic server
// tonic::transport::Server::builder()
//     .layer(DebugLayer::new())
//     .add_service(my_service)
//     .serve(addr)
//     .await?;

Configuration

use tonic_debug::{DebugLayer, DebugConfig};

let layer = DebugLayer::with_config(DebugConfig {
    log_headers: true,
    log_bodies: true,
    log_response_frames: true,
    max_body_bytes: 8192,
    hex_dump: false,
});

Connection Tracking

use tonic_debug::ConnectionMetrics;

let metrics = ConnectionMetrics::new();
// Use metrics.active_connections(), metrics.total_connections(), etc.

Feature Flags

Feature	Description
opentelemetry	Adds OpenTelemetry span attributes and export

Re-exports

pub use connection::ConnectionGuard;

pub use connection::ConnectionMetrics;

pub use connection::ConnectionTrackerLayer;

pub use layer::DebugConfig;

pub use layer::DebugLayer;

pub use service::DebugService;

Modules

body

Response body wrapper for capturing gRPC response data.

connection

Connection lifecycle observability.

inspect

Human-readable protobuf wire format inspection.

layer

Tower Layer implementation for the gRPC debug middleware.

service

Tower Service implementation for gRPC request/response interception.