gRPC Python Observability

Module Contents

class grpc_observability.OpenTelemetryObservability(*, plugins=None)

OpenTelemetry based plugin implementation.

This is class is part of an EXPERIMENTAL API.

Parameters:

plugin – OpenTelemetryPlugin to enable.

create_client_call_tracer(method_name, target)

Creates a ClientCallTracerCapsule.

After register the plugin, if tracing or stats is enabled, this method will be called after a call was created, the ClientCallTracer created by this method will be saved to call context.

The ClientCallTracer is an object which implements grpc_core::ClientCallTracer interface and wrapped in a PyCapsule using client_call_tracer as name.

Parameters:

• method_name (bytes) – The method name of the call in byte format.

• target (bytes) – The channel target of the call in byte format.

Returns:

A PyCapsule which stores a ClientCallTracer object.

Return type:

Any

create_server_call_tracer_factory()

Creates a ServerCallTracerFactoryCapsule.

After register the plugin, if tracing or stats is enabled, this method will be called by calling observability_init, the ServerCallTracerFactory created by this method will be registered to gRPC core.

The ServerCallTracerFactory is an object which implements grpc_core::ServerCallTracerFactory interface and wrapped in a PyCapsule using server_call_tracer_factory as name.

Returns:

A PyCapsule which stores a ServerCallTracerFactory object.

Return type:

Any

delete_client_call_tracer(client_call_tracer)

Deletes the ClientCallTracer stored in ClientCallTracerCapsule.

After register the plugin, if tracing or stats is enabled, this method will be called at the end of the call to destroy the ClientCallTracer.

The ClientCallTracer is an object which implements grpc_core::ClientCallTracer interface and wrapped in a PyCapsule using client_call_tracer as name.

Parameters:

client_call_tracer (Any) – A PyCapsule which stores a ClientCallTracer object.

Return type:

None

record_rpc_latency(method, target, rpc_latency, status_code)

Record the latency of the RPC.

After register the plugin, if stats is enabled, this method will be called at the end of each RPC.

Parameters:

• method (str) – The fully-qualified name of the RPC method being invoked.

• target (str) – The target name of the RPC method being invoked.

• rpc_latency (float) – The latency for the RPC in seconds, equals to the time between when the client invokes the RPC and when the client receives the status.

• status_code (StatusCode) – An element of grpc.StatusCode in string format representing the final status for the RPC.

Return type:

None

save_trace_context(trace_id, span_id, is_sampled)

Saves the trace_id and span_id related to the current span.

After register the plugin, if tracing is enabled, this method will be called after the server finished sending response.

This method can be used to propagate census context.

Parameters:

• trace_id (str) – The identifier for the trace associated with the span as a 32-character hexadecimal encoded string, e.g. 26ed0036f2eff2b7317bccce3e28d01f

• span_id (str) – The identifier for the span as a 16-character hexadecimal encoded string. e.g. 113ec879e62583bc

• is_sampled (bool) – A bool indicates whether the span is sampled.

Return type:

None

class grpc_observability.OpenTelemetryPlugin

Describes a Plugin for OpenTelemetry observability.

This is class is part of an EXPERIMENTAL API.

generic_method_attribute_filter(method)

Once overridden, this will be called with a generic method type to decide whether to record the method name or to replace it with “other”.

Note that pre-registered methods will always be recorded no matter what this function returns.

Parameters:

method (str) – The method name for the RPC.

Returns:

True means the original method name will be used, False means method name will be replaced with “other”.

Return type:

bool

get_meter_provider()

This function will be used to get the MeterProvider for this OpenTelemetryPlugin instance.

Returns:

A MeterProvider which will be used to collect telemetry data, or None which means no metrics will be collected.

Return type:

MeterProvider | None

get_plugin_options()

This function will be used to get plugin options which are enabled for this OpenTelemetryPlugin instance.

Returns:

An Iterable of class OpenTelemetryPluginOption which will be enabled for this OpenTelemetryPlugin.

Return type:

Iterable[OpenTelemetryPluginOption]

target_attribute_filter(target)

Once overridden, this will be called per channel to decide whether to record the target attribute on client or to replace it with “other”. This helps reduce the cardinality on metrics in cases where many channels are created with different targets in the same binary (which might happen for example, if the channel target string uses IP addresses directly).

Parameters:

target (str) – The target for the RPC.

Returns:

True means the original target string will be used, False means target string will be replaced with “other”.

Return type:

bool