Observability

couchbase.observability

couchbase.observability.get_otel_meter(provider: MeterProvider | None = None) → Meter

Create a meter that sends the SDK’s metrics to OpenTelemetry.

Parameters:

provider – The meter provider to get the meter from. Defaults to None, which uses the global one.

Returns:

The meter, an OtelWrapperMeter.

Raises:

ImportError – If OpenTelemetry is not installed.

couchbase.observability.get_otel_tracer(provider: TracerProvider | None = None) → RequestTracer

Create a tracer that sends the SDK’s spans to OpenTelemetry.

Parameters:

provider – The tracer provider to get the tracer from. Defaults to None, which uses the global one.

Returns:

The tracer, an OtelWrapperTracer.

Raises:

ImportError – If OpenTelemetry is not installed.

couchbase.observability.tracing

class couchbase.observability.tracing.RequestSpan

Represents a single traced operation (span) in distributed tracing.

Warning

couchbase.tracing.CouchbaseSpan is deprecated, and will be removed in a future release. Import RequestSpan from couchbase.observability.tracing.

A RequestSpan provides methods to add metadata (attributes), record events, set the final status, and mark the completion of an operation.

abstract add_event(name: str, attributes: Mapping[str, str | bool | int | float | Sequence[str] | Sequence[bool] | Sequence[int] | Sequence[float]] | None = None, timestamp: int | None = None) → None

Add a timestamped event to the span.

Parameters:
  • name – The event’s name.

  • attributes – Attributes of the event. Defaults to None.

  • timestamp – When the event happened, in nanoseconds since the epoch. Defaults to None, which is now.

abstract end(end_time: int | None) → None

Mark the span complete.

Parameters:

end_time – When the operation ended, in nanoseconds since the epoch, or None for now.

property is_recording: bool

Whether the span records what is set on it.

A span that is not sampled can return False, and the SDK then sets nothing on it. Defaults to True.

abstract property name: str

The name of the operation the span traces.

abstract set_attribute(key: str, value: str | bool | int | float | Sequence[str] | Sequence[bool] | Sequence[int] | Sequence[float]) → None

Sets a single attribute (key-value pair) on the span.

Parameters:
  • key – The attribute key.

  • value – The attribute value.

abstract set_attributes(attributes: Mapping[str, str | bool | int | float | Sequence[str] | Sequence[bool] | Sequence[int] | Sequence[float]]) → None

Sets multiple attributes on the span.

Parameters:

attributes – A mapping of attribute keys to values.

abstract set_status(status: SpanStatusCode) → None

Sets the final status of the span.

Parameters:

status – The span status.

class couchbase.observability.tracing.RequestTracer

Interface for creating and managing distributed tracing spans.

Warning

couchbase.tracing.CouchbaseTracer is deprecated, and will be removed in a future release. Import RequestTracer from couchbase.observability.tracing.

A RequestTracer is responsible for creating new spans to track operations.

abstract request_span(name: str, parent_span: RequestSpan | None = None, start_time: int | None = None) → RequestSpan

Start a span for an operation.

Parameters:
  • name – The name of the operation.

  • parent_span – The span of the operation this one is part of. Defaults to None.

  • start_time – When the operation started, in nanoseconds since the epoch. Defaults to None, which is now.

Returns:

A new RequestSpan.

couchbase.observability.tracing.SpanAttributeValue = str | bool | int | float | collections.abc.Sequence[str] | collections.abc.Sequence[bool] | collections.abc.Sequence[int] | collections.abc.Sequence[float]

Represent a PEP 604 union type

E.g. for int | str

couchbase.observability.tracing.SpanAttributes

A Mapping is a generic container for associating key/value pairs.

This class provides concrete generic implementations of all methods except for __getitem__, __iter__, and __len__.

alias of Mapping[str, str | bool | int | float | Sequence[str] | Sequence[bool] | Sequence[int] | Sequence[float]]

class couchbase.observability.tracing.SpanStatusCode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

The outcome a span records: UNSET until it is known, then OK or ERROR.

ERROR = 2
OK = 1
UNSET = 0

couchbase.observability.metrics

class couchbase.observability.metrics.Meter

The interface a source of value recorders implements.

Warning

couchbase.metrics.CouchbaseMeter is deprecated, and will be removed in a future release. Import Meter from couchbase.observability.metrics.

Implement it, with ValueRecorder, to send the SDK’s metrics to a metrics library of your own. get_otel_meter() returns one that sends them to OpenTelemetry.

abstract value_recorder(name: str, tags: Mapping[str, Any]) → ValueRecorder

Get the recorder for a metric and set of tags.

Parameters:
  • name (str) – The metric’s name.

  • tags (Mapping[str, Any]) – The tags each measurement carries. A __unit tag names the unit the metric is reported in, and is s for a duration the SDK records in microseconds.

Returns:

The recorder.

Return type:

ValueRecorder

class couchbase.observability.metrics.ValueRecorder

The interface a recorder of one metric implements.

Warning

couchbase.metrics.CouchbaseValueRecorder is deprecated, and will be removed in a future release. Import ValueRecorder from couchbase.observability.metrics.

Implement it to send the SDK’s metrics to a metrics library of your own.

abstract record_value(value: int) → None

Record one measurement.

Parameters:

value (int) – The measurement. A duration is in microseconds.