OpenTelemetry gRPC protocol

Registers the grpc OTLP protocol with Piko's OpenTelemetry driver, providing trace and metric exporters that talk to any OTLP collector over gRPC.

Overview

This is a blank-import package. Importing it runs an init() that calls driver_handlers.RegisterOtlpProtocol("grpc", ...). That makes the grpc protocol selectable in the OpenTelemetry configuration consumed by logger_otel_sdk. There is no constructor, no Config struct, and no value returned. The side effect of the import is the registration, so adding gRPC OTLP export takes one blank import and no wiring code.

The package registers two factories from the upstream exporters in go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc and otlptrace/otlptracegrpc. One factory builds the trace exporter and one builds the metric exporter. Each exporter dials its own gRPC connection to the configured endpoint. There is no OTLP log signal in this integration.

Both factories read one OtelSetupConfig, so a single config block (Endpoint, TLSInsecure, Headers) drives both signals. The package consumes those values. It does not own them. TLSInsecure: true selects plaintext gRPC for development. Setting it to false selects TLS against the system root CA pool. Custom headers, for example authentication tokens for SaaS OTLP backends, ride as gRPC per-RPC credentials.

The transport is pluggable behind the same OtlpProtocol registry. Switching between gRPC and HTTP is a one-line protocol change plus a swap of the imported package, because logger_integration_otel_http registers http and https with the identical factory shape.

Pair this with logger_otel_sdk, which provides the SDK provider factory, and either metrics_exporter_prometheus or a downstream OTLP collector to complete the pipeline.

Requirements

  • A reachable OTLP/gRPC endpoint, typically the OpenTelemetry Collector on :4317. SaaS backends such as Honeycomb, Grafana Cloud, and Datadog accept OTLP/gRPC directly.
  • The logger_otel_sdk package imported as well. It registers the provider factory that calls GetOtlpProtocol("grpc") to look up this registration. If you import only the gRPC package and enable OTLP, the framework logs a warning that no OTEL provider factory is registered and falls back to noop providers, so it exports nothing. Importing logger_otel_sdk registers that factory.

Configuration

The gRPC package has no Go-level configuration. The blank import is the registration. The OTLP endpoint, protocol, TLS, and headers come from the central otlp config, sourced from piko.yaml, environment variables, flags, or the piko.WithOTLP* options.

import (
    _ "piko.sh/piko/wdk/logger/logger_integration_otel_grpc"
    _ "piko.sh/piko/wdk/logger/logger_otel_sdk"
)

OTLP export defaults to off. The protocol defaults to http. To use this integration you turn export on and select grpc. With the imports alone and no enable flag, the SDK builds noop providers and exports nothing.

otlp:
  enabled: true
  protocol: grpc
  endpoint: localhost:4317
  tls:
    insecure: true
  headers:
    x-api-key: your-token

The matching environment variables are PIKO_OTLP_ENABLED, PIKO_OTLP_PROTOCOL, PIKO_OTLP_ENDPOINT, PIKO_OTLP_TLS_INSECURE, and PIKO_OTLP_HEADERS.

The TLS setting defaults to insecure: true, so the default connection is plaintext. Headers, including auth tokens, ride over that plaintext connection because the per-RPC credentials do not require transport security. For a SaaS or remote backend, set insecure: false so the token travels over TLS.

Bootstrap

The blank imports register the protocol and the SDK factory. You still enable OTLP and select grpc. Configure both in code with the piko.WithOTLP* options.

app := piko.New(
    piko.WithOTLPEnabled(true),
    piko.WithOTLPProtocol("grpc"),
    piko.WithOTLPEndpoint("localhost:4317"),
    piko.WithOTLPHeaders(map[string]string{"x-api-key": "your-token"}),
    piko.WithOTLPInsecureTLS(false),
)

piko.WithOTLP(piko.OtlpConfig{...}) replaces the entire OTLP config in one value. piko.WithOTLPTraceSampleRate(rate) sets the trace sample fraction.

See also

Sibling OTEL integrations:

Other logger integrations:

  • Sentry, error reporting with OTEL trace correlation.
  • File, file-based log persistence.
  • Prometheus, Prometheus scrape endpoint for metrics.

Framework docs:

External: