IBM Watsonx | Respan Docs

IBM Watsonx is IBM’s enterprise AI platform that provides foundation models, generative AI, and machine learning tools. It offers models like Granite and supports text generation, summarization, and classification for enterprise workloads. Respan gives you full observability over every Watsonx call, prompt, and decoding step — and gateway routing through the OpenAI-compatible Respan endpoint.

Set up Respan

Create an account at platform.respan.ai and grab an API key. For gateway, also add credits or a provider key.

Run npx @respan/cli setup to set up with your coding agent.

Example projects

Python examples

Tracing

Gateway

Setup

Install packages

$ pip install respan-ai opentelemetry-instrumentation-watsonx ibm-watsonx-ai

Set environment variables

$ export WATSONX_API_KEY="YOUR_WATSONX_API_KEY"
$ export WATSONX_PROJECT_ID="YOUR_WATSONX_PROJECT_ID"
$ export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

WATSONX_* are used for Watsonx requests. RESPAN_API_KEY is used to export traces to Respan.

Initialize and run

1 import os
2 from ibm_watsonx_ai.foundation_models import Model
3 from ibm_watsonx_ai.metanames import GenTextParamsMetaNames
4 from respan import Respan
5 from opentelemetry.instrumentation.watsonx import WatsonxInstrumentor
6 
7 respan = Respan(instrumentations=[WatsonxInstrumentor()])
8 
9 params = {
10     GenTextParamsMetaNames.MAX_NEW_TOKENS: 100,
11     GenTextParamsMetaNames.TEMPERATURE: 0.7,
12 }
13 
14 model = Model(
15     model_id="ibm/granite-13b-instruct-v2",
16     credentials={
17         "apikey": os.environ["WATSONX_API_KEY"],
18         "url": "https://us-south.ml.cloud.ibm.com",
19     },
20     project_id=os.environ["WATSONX_PROJECT_ID"],
21     params=params,
22 )
23 
24 response = model.generate_text("Say hello in three languages.")
25 print(response)
26 respan.flush()

View your trace

Open the Traces page to see your auto-instrumented Watsonx spans with prompts, tokens, and decoding parameters.

Configuration

Parameter	Type	Default	Description
`api_key`	`str \| None`	`None`	Falls back to `RESPAN_API_KEY` env var.
`base_url`	`str \| None`	`None`	Falls back to `RESPAN_BASE_URL` env var.
`instrumentations`	`list`	`[]`	Plugin instrumentations to activate (e.g. `WatsonxInstrumentor()`).
`customer_identifier`	`str \| None`	`None`	Default customer identifier for all spans.
`metadata`	`dict \| None`	`None`	Default metadata attached to all spans.
`environment`	`str \| None`	`None`	Environment tag (e.g. `"production"`).

Attributes

In Respan()

Set defaults at initialization — these apply to all spans.

1 from respan import Respan
2 from opentelemetry.instrumentation.watsonx import WatsonxInstrumentor
3 
4 respan = Respan(
5     instrumentations=[WatsonxInstrumentor()],
6     customer_identifier="user_123",
7     metadata={"service": "watsonx-api", "version": "1.0.0"},
8 )

With propagate_attributes

Override per-request using a context scope.

1 from respan import Respan, propagate_attributes
2 from opentelemetry.instrumentation.watsonx import WatsonxInstrumentor
3 
4 respan = Respan(instrumentations=[WatsonxInstrumentor()])
5 
6 def handle_request(user_id: str, prompt: str):
7     with propagate_attributes(
8         customer_identifier=user_id,
9         thread_identifier="conv_abc_123",
10         metadata={"plan": "pro"},
11     ):
12         print(model.generate_text(prompt))

Attribute	Type	Description
`customer_identifier`	`str`	Identifies the end user in Respan analytics.
`thread_identifier`	`str`	Groups related messages into a conversation.
`metadata`	`dict`	Custom key-value pairs. Merged with default metadata.