Python APIbedrock

Core

Instrumentation

Python · Instrumentation

openinference-instrumentation-bedrock

OpenInference Bedrock Instrumentation

Module
openinference.instrumentation.bedrock
Version
0.1.67
Python
>=3.10, <3.15
Instruments
boto3 >= 1.40.46

Install

pip install openinference-instrumentation-bedrock

Usage

Instrument once, at startup, before the library is used. The BedrockInstrumentor reference below lists the options.

from opentelemetry.sdk.trace import TracerProvider
from openinference.instrumentation import TraceConfig
from openinference.instrumentation.bedrock import BedrockInstrumentor

tracer_provider = TracerProvider()
# ...add a span processor that exports to Phoenix or any OTLP backend.

BedrockInstrumentor().instrument(
    tracer_provider=tracer_provider,
    config=TraceConfig(hide_inputs=True),  # optional
)

openinference.instrumentation.bedrock

OpenInference instrumentation for AWS Bedrock (boto3 and aioboto3).

This module patches botocore’s ClientCreator and aiobotocore’s AioClientCreator so that Bedrock clients (bedrock-runtime and bedrock-agent-runtime) are instrumented with OpenTelemetry spans. Sync and async clients are handled separately: sync uses _model_invocation_wrapper and BufferedStreamingBody for invoke_model; async uses _async_model_invocation_wrapper and _LazyAsyncInvokeModelBody so that the response body is read only when the caller awaits read(), and span attributes are set at that time.

Streaming APIs (invoke_model_with_response_stream, converse_stream, invoke_agent, etc.) use wrappers that start a span and wrap the event stream so the span is ended when the stream is fully consumed, closed, or dropped.

Request/response body types (from botocore/aiobotocore service shapes): InvokeModel request body is the API body payload (shape blob), so kwargs[“body”] may be str, bytes, or a seekable file-like object (e.g. io.BytesIO); file-like bodies are read and restored before parsing. Response body is botocore’s StreamingBody (sync read) or aiobotocore’s StreamingBody (async read) respectively.

Edge cases and limitations:

  • Suppression: All wrappers check _SUPPRESS_INSTRUMENTATION_KEY first and call through unwrapped without creating spans.
  • Errors: API or parse failures set span status to ERROR, record_exception when we handle the exception, and end the span. Sync invoke_model uses a context manager that also records and sets status on any uncaught exception.
  • Async invoke_model: Span is completed on first read() of the response body, or in del if the body is never read (best-effort).
  • Streaming: Span ends when the event stream is fully consumed or on first exception. A stream that is closed or dropped before its end ends the span with the output read so far and leaves the status unset.
  • Double consumption of the same stream is not supported; the underlying stream is single-read.
  • Missing response body: If InvokeModel returns without a body we raise ValueError after setting span status to ERROR.

InstrumentedClient

classSource ↗
class InstrumentedClient(BaseClient)

Type stub for an instrumented Bedrock client.

After _instrument_client() runs, the client’s Bedrock API methods are replaced with wrapped versions that create spans and set OpenInference attributes. The original methods are stored as unwrapped* so the wrappers can call through.

Attributes

NameType and value
invoke_modelCallable[..., Any]
converseCallable[..., Any]
invoke_agentCallable[..., Any]
invoke_inline_agentCallable[..., Any]
retrieveCallable[..., Any]
retrieve_and_generateCallable[..., Any]
retrieve_and_generate_streamCallable[..., Any]
apply_guardrailCallable[..., Any]

BufferedStreamingBody

classSource ↗
class BufferedStreamingBody(raw_stream: IO[bytes], content_length: int)

Sync streaming body that buffers the full response on first read(), so we can parse it for span attributes and then reset() to allow the caller to read again.

Used by the sync invoke_model wrapper: read once for attribution, reset(), then return the same body to the caller. Expects botocore’s StreamingBody interface (_raw_stream, _content_length).

read

methodSource ↗
def read(amt: Optional[int] = None) -> bytes

reset

methodSource ↗
def reset() -> None

Rewind the buffer so the body can be read again by the caller.

BedrockInstrumentor

classSource ↗
class BedrockInstrumentor(BaseInstrumentor)

OpenTelemetry instrumentor for AWS Bedrock (boto3 and aiobotocore).

Patches ClientCreator.create_client (sync) and AioClientCreator.create_client (async) so that newly created clients have their Bedrock API methods wrapped. Sync and async clients are instrumented independently; aiobotocore is optional.

instrument

method
def instrument(
    *,
    tracer_provider: Optional[TracerProvider] = None,
    config: Optional[TraceConfig] = None,
    skip_dep_check: bool = False,
) -> None

Start tracing boto3: patch it so its calls make OpenInference spans. Calling it again does nothing. Inherited from OpenTelemetry’s BaseInstrumentor.

Parameters

NameDescription
tracer_provider

The tracer provider the spans are made with. Defaults to the global one, opentelemetry.trace.get_tracer_provider().

config

What the spans record: hide inputs, outputs or messages, or limit image sizes. Defaults to TraceConfig(), which reads the OPENINFERENCE_* environment variables. See TraceConfig.

skip_dep_check

Instrument even if the installed version of boto3 is outside the supported range.

uninstrument

method
def uninstrument() -> None

Stop tracing: undo the patches instrument() made. Inherited from OpenTelemetry’s BaseInstrumentor.

instrumentation_dependencies

methodSource ↗
def instrumentation_dependencies() -> Collection[str]

openinference.instrumentation.bedrock.utils.json_utils

parse_invoke_model_body

functionSource ↗
def parse_invoke_model_body(body: Any) -> Any

Parse an InvokeModel request body that may be str, bytes, or a file-like object.

boto3 documents body as “bytes or seekable file-like object”. A file-like body is read from its current position, where botocore also starts sending. If it was already read to the end, as it is once the request is sent, it is read again from the start. Its position is restored afterwards so the request is unaffected.

fix_loose_json_string

functionSource ↗
def fix_loose_json_string(s: str) -> list[dict[str, Any]]

Converts a loosely formatted JSON string into a list of dictionaries.

Parameters

NameTypeDescription
sstr

The loosely formatted JSON string.

Returns

TypeDescription
list[dict[str, Any]]

list[dict[str, Any]]: A list of dictionaries parsed from the string.

sanitize_json_input

functionSource ↗
def sanitize_json_input(bad_json_str: str) -> str

Cleans a JSON string by escaping invalid backslashes.

Parameters

NameTypeDescription
bad_json_strstr

The JSON string with potential invalid backslashes.

Returns

TypeDescription
str

The sanitized JSON string.

safe_json_loads

functionSource ↗
def safe_json_loads(json_str: str) -> Any

Safely loads a JSON string, attempting to sanitize it if initial loading fails.

Parameters

NameTypeDescription
json_strstr

The JSON string to load.

Returns

TypeDescription
Any

The loaded JSON object.