Observability for proxyless gRPC

C++

Observability support is only available through the Bazel build system. The target grpcpp_csm_observability needs to be added as a dependency.

Required code changes

The following code needs to be added to your gRPC clients and servers in order to make use of Cloud Service Mesh observability.

#include <grpcpp/ext/csm_observability.h>

int main() {
  // …
  auto observability = grpc::CsmObservabilityBuilder()
                          .SetMeterProvider(std::move(meter_provider))
                          .BuildAndRegister();
  assert(observability.ok());
  // …
}

Before any gRPC operations, including creating a channel, server, or credentials, use the CsmObservabilityBuilder API to register a plugin. The following sample shows how to set up Cloud Service Mesh Observability with a Prometheus exporter.

  opentelemetry::exporter::metrics::PrometheusExporterOptions opts;
  opts.url = "0.0.0.0:9464";
  auto prometheus_exporter =
      opentelemetry::exporter::metrics::PrometheusExporterFactory::Create(opts);
  auto meter_provider =
      std::make_shared<opentelemetry::sdk::metrics::MeterProvider>();
  meter_provider->AddMetricReader(std::move(prometheus_exporter));
  auto observability = grpc:::CsmObservabilityBuilder()
                          .SetMeterProvider(std::move(meter_provider))
                          .BuildAndRegister();

The SetMeterProvider() API on CsmObservabilityBuilder() allows users to set a MeterProvider object that can be configured with exporters.

Java

To enable Cloud Service Mesh Observability for Java gRPC applications, perform the following steps:

1. Ensure project includes the grpc-gcp-csm-observability artifact. Use gRPC version 1.65.0 or later.

2. Within main() method, initialize Cloud Service Mesh Observability by providing a configured OpenTelemetry SDK instance with a MeterProvider to collect and export metrics.

   Before you perform any gRPC operations like setting up a channel or server, make sure to use the CsmObservability.Builder() API to register OpenTelemetry SDK.

   Once the CsmObservability instance is created, invoking registerGlobal() on the instance enables Cloud Service Mesh Observability for all Cloud Service Mesh channels and servers.

   The following example demonstrates how to set up Cloud Service Mesh Observability using a Prometheus exporter.

import io.grpc.gcp.csm.observability.CsmObservability;
...

public static void main(String[] args) {
    ...

    int prometheusPort = 9464;

    SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder()
        .registerMetricReader(
            PrometheusHttpServer.builder().setPort(prometheusPort).build())
        .build();

    OpenTelemetrySdk openTelemetrySdk = OpenTelemetrySdk.builder()
        .setMeterProvider(sdkMeterProvider)
        .build();

    CsmObservability observability = new CsmObservability.Builder()
        .sdk(openTelemetrySdk)
        .build();
    observability.registerGlobal();

    // ... (continue with channel and server configuration)
}

Go

Before any gRPC operations, including creating a ClientConn or Server, or credentials, configure Cloud Service Mesh Observability globally with a MeterProvider. The following sample shows how to set up Cloud Service Mesh Observability. After setting Cloud Service MeshObservability up, any Cloud Service Mesh Channels and all servers will pick up an OpenTelemetry stats plugin configured with provided options and with additional Cloud Service Mesh Labels. Non Cloud Service Mesh Channels will get an OpenTelemetry stats plugin without Cloud Service Mesh Labels.

  import (
  "context"

  "google.golang.org/grpc/stats/opentelemetry"
  "google.golang.org/grpc/stats/opentelemetry/csm"

  "go.opentelemetry.io/otel/sdk/metric"
)

func main() {
  reader := metric.NewManualReader()
  provider := metric.NewMeterProvider(metric.WithReader(reader))
  opts := opentelemetry.Options{
    MetricsOptions: opentelemetry.MetricsOptions{
        MeterProvider: provider,
    },
  }
  cleanup := csm.EnableObservability(context.Background(), opts)
  defer cleanup()
  // Any created ClientConns and servers will be configured with an
  // OpenTelemetry stats plugin configured with provided options.

}

Python

The following gRPC dependencies are required for Cloud Service Mesh Observability:

grpcio>=1.65.0
grpcio-observability>=1.65.0
grpcio-csm-observability>=1.65.0

Before any gRPC operations, including creating a channel, server, or credentials, use the CsmOpenTelemetryPlugin API to create and register a plugin:

import grpc_csm_observability

# ...
csm_plugin = grpc_csm_observability.CsmOpenTelemetryPlugin(
    meter_provider=[your_meter_provider],
)
csm_plugin.register_global()

# Create server or client 

After all gRPC operations, use the following code to deregister and clean up resources:

csm_plugin.deregister_global()

The following sample shows how to set up Cloud Service Mesh Observability with a Prometheus exporter:

import grpc_csm_observability
from opentelemetry.exporter.prometheus import PrometheusMetricReader
from prometheus_client import start_http_server

start_http_server(port=9464, addr="0.0.0.0")
reader = PrometheusMetricReader()
meter_provider = MeterProvider(metric_readers=[reader])
csm_plugin = CsmOpenTelemetryPlugin(
    meter_provider=meter_provider,
)
csm_plugin.register_global()

# Clean up after use

csm_plugin.deregister_global()