Monitoring gRPC transport

Server-side implementation of the piko.monitoring.v1 API. Hosts a gRPC server inside the running Piko app that exposes registered routes, telemetry, profiling, health, and watchdog state to the Piko CLI and TUI.

Overview

The package's entry point is Transport(opts ...Option). It returns a monitoring_domain.TransportFactory that you pass to piko.WithMonitoringTransport. You write one line. The factory builds the gRPC server when the monitoring service starts, with the address, TLS, and dependency container threaded through from piko.WithMonitoring(...). No manual server, listener, or credential plumbing.

Service registration tracks what the app has wired. The health service always registers. The metrics service registers when a telemetry, system-stats, or resource provider is present. The inspector services register only when their dependency is non-nil, so the wire surface matches the running app. Enabling a feature surfaces its gRPC service with no extra registration code: piko.WithMonitoringProfiling() adds the profiling service, and piko.WithMonitoringWatchdog() adds the watchdog inspector. The orchestrator, registry, dispatcher, rate-limiter, and provider-info inspectors appear when the corresponding subsystem is active. gRPC reflection is on by default, so grpcurl and the standard CLI list methods without a precompiled protoset.

config.AutoNextPort (set on piko.WithMonitoringAutoNextPort) handles the case where the configured port is already in use. The transport tries consecutive ports, up to 100 attempts, and binds to the first free one. That helps when Piko instances run side-by-side on a developer machine. Set the address to :0 to let the operating system pick a free port on the first try.

The transport supports TLS directly. WithMonitoringTLS and its sub-options point at certificate, key, and optional client-CA files. The transport wires those into gRPC server credentials and reloads them on change via WithMonitoringTLSHotReload. Without TLS the server runs in plaintext.

This is the package that the standard CLI talks to. If you import it but never call Transport(), the monitoring service stays disabled. Registration is opt-in. The transport's lifecycle follows the monitoring service's Start and Stop. A panic-recovery interceptor turns handler panics into clean Internal errors. Shutdown runs GracefulStop to drain in-flight RPCs, then falls back to a forced stop after 10 seconds. The server's Start, Stop, and Address methods are safe for concurrent use.

Requirements

  • A reachable port for the gRPC listener. Set the address via piko.WithMonitoringAddress. An address of :0 lets the operating system assign a free port.
  • The server binds to 127.0.0.1 by default, reachable from the local host only. To expose it to other hosts, set piko.WithMonitoringBindAddress("0.0.0.0"). The server prepends the bind address to any address that starts with :.
  • For TLS, certificate and key files (PEM) on disk, plus an optional client-CA file for mTLS.
  • Pair with logger_otel_sdk.OtelServiceFactories() when you want span and metrics data to flow into the transport's TelemetryStore for the CLI and TUI to consume.

The package is pure Go. It needs no build tags, no CGO, and no system libraries, so it runs in both compiled and interpreted dev modes.

Configuration

Transport(opts...) accepts package-local Option values for gRPC-specific tuning. Set server addressing and TLS at the piko.WithMonitoring(...) level, not here.

import (
    "google.golang.org/grpc"

    "piko.sh/piko/wdk/monitoring/monitoring_transport_grpc"
)

factory := monitoring_transport_grpc.Transport(
    monitoring_transport_grpc.WithReflection(true), // default, exposes the gRPC reflection service
    monitoring_transport_grpc.WithGRPCServerOptions(
        grpc.MaxRecvMsgSize(8*1024*1024), // optional, raises the default 4 MiB receive cap
    ),
)

Reflection exposes the full API surface. Pass WithReflection(false) to disable it in production.

Bootstrap

import (
    "piko.sh/piko"
    "piko.sh/piko/wdk/logger/logger_otel_sdk"
    "piko.sh/piko/wdk/monitoring/monitoring_transport_grpc"
)

ssr := piko.New(
    piko.WithMonitoring(
        piko.WithMonitoringAddress(":9091"),
        piko.WithMonitoringAutoNextPort(true),
        piko.WithMonitoringTransport(monitoring_transport_grpc.Transport()),
        piko.WithMonitoringOtelFactories(logger_otel_sdk.OtelServiceFactories()),
    ),
)

WithMonitoringTransport wires the factory. WithMonitoringOtelFactories is what makes spans and metrics show up in the TUI, by giving the monitoring service real OTEL adapters that record into the shared TelemetryStore.

See also

The wire format this server implements:

The typical OTEL data source:

Other logger integrations:

  • Prometheus, alternative metrics surface for external scrapers.
  • Sentry, error reporting alongside the in-process telemetry.

Framework docs:

External: