{"id":2650,"library":"opentelemetry-instrumentation-watsonx","title":"OpenTelemetry IBM Watsonx Instrumentation","description":"This library provides OpenTelemetry tracing for applications using IBM Watsonx. It instruments interactions with Watsonx AI services, capturing LLM calls, parameters, and responses as OpenTelemetry spans. The project is actively maintained with frequent releases, often aligning with updates to OpenTelemetry GenAI semantic conventions. Current version: 0.58.0.","status":"active","version":"0.58.0","language":"en","source_language":"en","source_url":"https://github.com/traceloop/openllmetry/tree/main/packages/opentelemetry-instrumentation-watsonx","tags":["opentelemetry","observability","tracing","ibm","watsonx","ai","llm","foundation-models"],"install":[{"cmd":"pip install opentelemetry-instrumentation-watsonx","lang":"bash","label":"Install library"}],"dependencies":[{"reason":"Core OpenTelemetry SDK components for tracing.","package":"opentelemetry-sdk"},{"reason":"The IBM Watsonx AI client library being instrumented.","package":"ibm-watson-machine-learning"}],"imports":[{"symbol":"WatsonxInstrumentation","correct":"from opentelemetry.instrumentation.watsonx import WatsonxInstrumentation"}],"quickstart":{"code":"import os\n\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.watsonx import WatsonxInstrumentation\n\n# Setup basic OpenTelemetry tracing (output to console)\nresource = Resource.create({\"service.name\": \"my-watsonx-app\"})\nprovider = TracerProvider(resource=resource)\nprovider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))\ntrace.set_tracer_provider(provider)\n\n# Initialize Watsonx instrumentation\nWatsonxInstrumentation().instrument()\n\n# Import the Watsonx client AFTER instrumentation\nfrom ibm_watson_machine_learning.foundation_models import Model\nfrom ibm_watson_machine_learning.foundation_models.utils.enums import ModelTypes\nfrom ibm_watson_machine_learning.foundation_models.inference import TextGenerationParameters\n\n# Watsonx client setup (replace with your actual API key and project ID)\n# It's recommended to use environment variables for sensitive info\napi_key = os.environ.get(\"WATSONX_API_KEY\", \"YOUR_WATSONX_API_KEY\")\nproject_id = os.environ.get(\"WATSONX_PROJECT_ID\", \"YOUR_WATSONX_PROJECT_ID\")\nurl = os.environ.get(\"WATSONX_URL\", \"https://us-south.ml.cloud.ibm.com\")\n\nif \"YOUR_WATSONX_API_KEY\" in api_key or \"YOUR_WATSONX_PROJECT_ID\" in project_id:\n    print(\"WARNING: Please set WATSONX_API_KEY and WATSONX_PROJECT_ID environment variables for a runnable example.\")\n\ncredentials = {\n    \"url\": url,\n    \"apikey\": api_key\n}\n\nparameters = TextGenerationParameters(\n    max_new_tokens=50,\n    min_new_tokens=10,\n    repetition_penalty=1.1\n)\n\n# Example model initialization and text generation\ntry:\n    model = Model(\n        model_id=ModelTypes.LLAMA_2_70B_CHAT, # Or other supported model\n        credentials=credentials,\n        parameters=parameters,\n        project_id=project_id,\n    )\n    \n    prompt = \"What is the capital of France?\"\n    print(f\"\\nGenerating text for prompt: '{prompt}'\")\n    response = model.generate_text(prompt=prompt)\n    print(f\"Generated text: {response}\")\n\nexcept Exception as e:\n    print(f\"Error during Watsonx API call: {e}\")\n    print(\"Ensure your WATSONX_API_KEY, WATSONX_PROJECT_ID, and WATSONX_URL are correctly set and have access.\")\n\n# Spans will be printed to console by ConsoleSpanExporter","lang":"python","description":"This quickstart demonstrates how to set up OpenTelemetry with `opentelemetry-instrumentation-watsonx`, initialize the instrumentation, and then use the `ibm-watson-machine-learning` client to generate text. It assumes you have a basic Watsonx setup with an API key and project ID configured. The traces will be printed to the console."},"warnings":[{"fix":"Regularly review the OpenTelemetry GenAI semantic conventions documentation (especially `gen_ai.*` attributes) and the instrumentation's release notes. Update your monitoring configurations to reflect any changes in span attributes.","message":"OpenTelemetry GenAI semantic conventions are actively evolving. Frequent updates to `opentelemetry-instrumentation-watsonx` often include changes to span attribute names, types, or structures to align with these conventions. This can impact existing monitoring dashboards, alerts, or analytics queries if not updated accordingly.","severity":"gotcha","affected_versions":"0.53.0 and newer (due to active development of GenAI semantic conventions)"},{"fix":"Ensure that `from opentelemetry.instrumentation.watsonx import WatsonxInstrumentation` and `WatsonxInstrumentation().instrument()` are executed early in your application's lifecycle, preferably before any `ibm_watson_machine_learning` imports or instantiations.","message":"The `WatsonxInstrumentation().instrument()` call must occur before any code that interacts with the `ibm-watson-machine-learning` library. If the `ibm-watson-machine-learning` client is imported or used before instrumentation is enabled, its operations will not be traced.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When upgrading, check the release notes for the main `openllmetry` project (if applicable to your setup) for any breaking changes or required synchronization across different `openllmetry` packages.","message":"This instrumentation package is part of the broader `openllmetry` project, which bundles various LLM instrumentations. While `opentelemetry-instrumentation-watsonx` can be used standalone, ensure compatibility if you are also using other `openllmetry` instrumentations or the `openllmetry` SDK, as version bumps and changes are often coordinated across the ecosystem.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}