Watsonx (tracing)

IBM watsonx.ai is IBM’s enterprise AI platform for foundation models and embeddings. Respan traces the official ibm-watsonx-ai Python SDK so direct Watsonx calls show up with prompts, completions, tool calls, embeddings, token usage, latency, workflow names, and custom metadata.

Use this page when your application calls Watsonx directly with IBM credentials.

Set up Respan

Create an account at platform.respan.ai and grab an API key .

Paste this into your coding agent:


Help me set up Respan tracing with the Watsonx integration.
Follow https://www.respan.ai/docs/integrations/watsonx.md

Setup

Install packages

Terminal


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

Set environment variables

Terminal


export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export WATSONX_API_KEY="YOUR_WATSONX_API_KEY"
export WATSONX_PROJECT_ID="YOUR_WATSONX_PROJECT_ID"
export WATSONX_URL="https://us-south.ml.cloud.ibm.com"

RESPAN_API_KEY exports traces to Respan. WATSONX_API_KEY, WATSONX_PROJECT_ID, and WATSONX_URL are used by the IBM Watsonx SDK.

Initialize and run

Python


import os

from ibm_watsonx_ai import Credentials
from ibm_watsonx_ai.foundation_models import ModelInference
from respan import Respan
from respan_instrumentation_watsonx import WatsonxInstrumentor

respan = Respan(instrumentations=[WatsonxInstrumentor()])

credentials = Credentials(
    api_key=os.environ["WATSONX_API_KEY"],
    url=os.getenv("WATSONX_URL", "https://us-south.ml.cloud.ibm.com"),
)

model = ModelInference(
    model_id=os.getenv("WATSONX_MODEL_ID", "ibm/granite-3-8b-instruct"),
    credentials=credentials,
    project_id=os.environ["WATSONX_PROJECT_ID"],
    validate=False,
)

response = model.generate(
    prompt="Say hello in three languages.",
    params={"max_new_tokens": 60},
)
print(response["results"][0]["generated_text"])

View your trace

Open the Traces page to see the Watsonx SDK spans with model names, prompt and completion content, token usage, latency, and metadata.

Supported calls

WatsonxInstrumentor() traces these official ibm-watsonx-ai SDK methods:

Class	Methods
`ModelInference`	`generate`, `generate_text`, `generate_text_stream`, `chat`, `chat_stream`, `agenerate`, `agenerate_stream`, `achat`, `achat_stream`
`Embeddings`	`generate`, `embed_query`, `embed_documents`, `agenerate`, `aembed_query`, `aembed_documents`

Chat spans include tool definitions from llm.request.functions and tool calls from the assistant completion. Embedding spans include inputs and usage metadata but do not export embedding vectors.

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, for example `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, for example `"production"`.

Attributes

In Respan()

Set defaults at initialization. These apply to all spans.

Python


from respan import Respan
from respan_instrumentation_watsonx import WatsonxInstrumentor

respan = Respan(
    instrumentations=[WatsonxInstrumentor()],
    customer_identifier="user_123",
    metadata={"service": "watsonx-api", "version": "1.0.0"},
    environment="production",
)

With propagate_attributes

Override attributes for a single request or workflow.

Python


from respan import Respan, propagate_attributes
from respan_instrumentation_watsonx import WatsonxInstrumentor

respan = Respan(instrumentations=[WatsonxInstrumentor()])

def handle_request(user_id: str, prompt: str):
    with propagate_attributes(
        customer_identifier=user_id,
        thread_identifier="conv_abc_123",
        metadata={"plan": "pro"},
    ):
        response = model.generate(prompt=prompt, params={"max_new_tokens": 60})
        print(response["results"][0]["generated_text"])

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.

Decorators (optional)

Decorators are not required. Watsonx SDK calls are auto-traced. Use @workflow and @task when you want to group related Watsonx calls into a named trace.

Python


from respan import Respan, workflow
from respan_instrumentation_watsonx import WatsonxInstrumentor

respan = Respan(instrumentations=[WatsonxInstrumentor()])

@workflow(name="watsonx_answer")
def answer(question: str):
    response = model.chat(
        messages=[{"role": "user", "content": question}],
        params={"max_new_tokens": 80},
    )
    return response["choices"][0]["message"]["content"]

print(answer("What does tracing capture?"))