or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

admin-services.mdbinary-logging.mdchannelz.mdhealth-checking.mdindex.mdload-balancing.mdmetrics.mdserver-reflection.md
tile.json

tessl/maven-io-grpc--grpc-services

gRPC service utilities providing health checking, server reflection, channelz observability, and binary logging capabilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.grpc/grpc-services@1.73.x

To install, run

npx @tessl/cli install tessl/maven-io-grpc--grpc-services@1.73.0

index.mddocs/

gRPC Services

gRPC Services is a comprehensive Java library that provides essential service utilities and implementations for gRPC applications. It includes health checking, server reflection, channelz observability, binary logging, and metrics recording capabilities for building production-ready gRPC servers.

Package Information

  • Package Name: io.grpc:grpc-services
  • Package Type: maven
  • Language: Java
  • Installation: Add to your pom.xml or build.gradle

Maven:

<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-services</artifactId>
    <version>1.73.0</version>
</dependency>

Gradle:

implementation 'io.grpc:grpc-services:1.73.0'

Core Imports

import io.grpc.protobuf.services.HealthStatusManager;
import io.grpc.protobuf.services.ProtoReflectionServiceV1;
import io.grpc.protobuf.services.ChannelzService;
import io.grpc.protobuf.services.BinaryLogs;
import io.grpc.services.CallMetricRecorder;
import io.grpc.services.MetricRecorder;
import io.grpc.services.AdminInterface;

Basic Usage

import io.grpc.Server;
import io.grpc.ServerBuilder;
import io.grpc.protobuf.services.HealthStatusManager;
import io.grpc.protobuf.services.ProtoReflectionServiceV1;
import io.grpc.services.AdminInterface;

// Create a gRPC server with health checking and reflection
HealthStatusManager healthManager = new HealthStatusManager();

Server server = ServerBuilder.forPort(8080)
    .addService(healthManager.getHealthService())
    .addService(ProtoReflectionServiceV1.newInstance())
    .addServices(AdminInterface.getStandardServices())
    .build();

// Set service health status
healthManager.setStatus("my.service", ServingStatus.SERVING);

// Start server
server.start();

Architecture

gRPC Services is organized around several key service areas:

  • Health Checking: Server health status management with support for per-service health reporting
  • Server Reflection: Protocol buffer service reflection for dynamic service discovery
  • Observability: Channelz service for runtime introspection and debugging
  • Binary Logging: Request/response logging for debugging and auditing
  • Metrics & Load Reporting: ORCA metrics collection for load balancing and performance monitoring
  • Admin Services: Standardized administrative service collection

Most APIs are marked as @ExperimentalApi indicating they are still evolving.

Capabilities

Health Checking Services

Server health status management for load balancer health checks and service monitoring. Provides both individual service status and overall server health reporting.

public final class HealthStatusManager {
  public static final String SERVICE_NAME_ALL_SERVICES = "";
  
  public HealthStatusManager();
  public BindableService getHealthService();
  public void setStatus(String service, ServingStatus status);
  public void clearStatus(String service);
  public void enterTerminalState();
}

Health Checking

Server Reflection Services

Protocol buffer service reflection enabling dynamic service discovery and debugging tools. Supports both v1alpha (deprecated) and v1 reflection protocols.

public final class ProtoReflectionServiceV1 {
  public static BindableService newInstance();
  public StreamObserver<ServerReflectionRequest> serverReflectionInfo(
    StreamObserver<ServerReflectionResponse> responseObserver
  );
}

Server Reflection

Channelz Observability

Runtime introspection service providing detailed information about gRPC channels, servers, and connections for debugging and monitoring.

public final class ChannelzService {
  public static ChannelzService newInstance(int maxPageSize);
  public void getTopChannels(GetTopChannelsRequest request, 
    StreamObserver<GetTopChannelsResponse> responseObserver);
  public void getServers(GetServersRequest request, 
    StreamObserver<GetServersResponse> responseObserver);
}

Channelz Observability

Binary Logging

Request and response logging system for debugging, auditing, and compliance. Supports configurable logging sinks and filtering.

public final class BinaryLogs {
  public static BinaryLog createBinaryLog() throws IOException;
  public static BinaryLog createBinaryLog(BinaryLogSink sink, String configStr) 
    throws IOException;
}

public interface BinaryLogSink extends Closeable {
  void write(MessageLite message);
}

Binary Logging

Metrics and Load Reporting

ORCA metrics collection for load balancing and performance monitoring. Includes both per-call and out-of-band metrics reporting.

public final class CallMetricRecorder {
  public static CallMetricRecorder getCurrent();
  public CallMetricRecorder recordUtilizationMetric(String name, double value);
  public CallMetricRecorder recordRequestCostMetric(String name, double value);
  public CallMetricRecorder recordCpuUtilizationMetric(double value);
}

public final class MetricRecorder {
  public static MetricRecorder newInstance();
  public void putUtilizationMetric(String key, double value);
  public void setCpuUtilizationMetric(double value);
}

Metrics and Load Reporting

Load Balancing Utilities

Client-side health checking utilities for load balancers and connection management.

public final class HealthCheckingLoadBalancerUtil {
  public static LoadBalancer newHealthCheckingLoadBalancer(
    LoadBalancer.Factory factory, Helper helper);
}

Load Balancing

Admin Services

Collection of standard administrative services for gRPC servers including all built-in observability and management services.

public final class AdminInterface {
  public static List<ServerServiceDefinition> getStandardServices();
}

Admin Services

Types

public enum ServingStatus {
  SERVING,
  NOT_SERVING,
  SERVICE_UNKNOWN
}

public class MetricReport {
  public double getCpuUtilization();
  public double getApplicationUtilization();
  public double getMemoryUtilization();
  public Map<String, Double> getRequestCostMetrics();
  public Map<String, Double> getUtilizationMetrics();
}