{"id":2171,"library":"opik","title":"Opik - LLM Observability and Evaluation","description":"Opik, built by Comet, is an open-source platform designed to streamline the entire lifecycle of LLM applications. It provides comprehensive tracing, evaluation, monitoring, and optimization capabilities for large language models and agentic systems, from prototype to production. The current version is 1.11.1 and it is under active development with frequent updates and a community-driven roadmap.","status":"active","version":"1.11.1","language":"python","source_language":"en","source_url":"https://github.com/comet-ml/opik","tags":["LLM","observability","evaluation","monitoring","tracing","AI","Comet"],"install":[{"cmd":"pip install opik","lang":"bash","label":"Install core SDK"},{"cmd":"pip install opik-optimizer","lang":"bash","label":"Install optimizer (optional)"}],"dependencies":[{"reason":"Required for advanced prompt and agent optimization features.","package":"opik-optimizer","optional":true},{"reason":"Used by the Opik Optimizer for various LLM providers; requires provider API keys to be set as environment variables.","package":"LiteLLM","optional":true}],"imports":[{"symbol":"track","correct":"from opik import track"},{"symbol":"Opik","correct":"import opik\nclient = opik.Opik()"},{"note":"ChatPrompt is part of the `opik-optimizer` package, not the core `opik` SDK.","wrong":"from opik import ChatPrompt","symbol":"ChatPrompt","correct":"from opik_optimizer import ChatPrompt"}],"quickstart":{"code":"import opik\nimport os\n\n# Configure Opik - for Comet.com Cloud\n# Replace with your actual API key and workspace, or run `opik configure` in your terminal\nopik.configure(\n    api_key=os.environ.get('OPIK_API_KEY', 'YOUR_OPIK_API_KEY'),\n    workspace=os.environ.get('OPIK_WORKSPACE', 'YOUR_OPIK_WORKSPACE'),\n    project_name=\"my-llm-project\"\n)\n\n@opik.track\ndef my_llm_function(user_question: str) -> str:\n    # Simulate an LLM call or business logic\n    response = f\"Echoing your question: {user_question}\"\n    # Log metadata or tags if needed\n    opik.set_tags([\"example\", \"basic-tracing\"])\n    opik.log_metadata({\"question_length\": len(user_question)})\n    return response\n\n# Run the traced function\nresult = my_llm_function(\"What is the capital of France?\")\nprint(f\"LLM Function Result: {result}\")\n\n# To view traces, run `opik dashboard` or visit your Comet.com Opik dashboard.","lang":"python","description":"This quickstart demonstrates how to instrument a Python function with the `@opik.track` decorator to automatically log LLM calls and associated metadata to the Opik platform. It includes configuration for both Comet.com Cloud and an example of setting environment variables for authentication."},"warnings":[{"fix":"Review the official changelog for Opik, especially regarding updates to self-hosting and potential configuration adjustments for client SDKs.","message":"Version 1.7.0 of Opik included important updates and breaking changes, particularly for self-hosted deployments. Users are advised to check the changelog for details.","severity":"breaking","affected_versions":">=1.7.0"},{"fix":"If not using Opik's Helm Chart or Docker Compose, manually add the `{cluster}` macro to your ClickHouse configuration file (e.g., `/etc/clickhouse-server/config.d/macros.xml`) and restart ClickHouse.","message":"For self-hosted Opik instances, ClickHouse must be configured with cluster macros, even for single-node deployments. Without this, migrations will fail with 'DB::Exception: No macro 'cluster' in config'.","severity":"gotcha","affected_versions":"All self-hosted versions"},{"fix":"Import `ChatPrompt` from `opik_optimizer` and wrap your messages list before passing it to an optimizer. Example: `from opik_optimizer import ChatPrompt; prompt = ChatPrompt(messages=[...])`.","message":"When using `opik-optimizer`, the prompt passed to any optimizer must be a `ChatPrompt` object, not a raw messages list.","severity":"gotcha","affected_versions":"All `opik-optimizer` versions"},{"fix":"Re-run `opik configure` from the terminal and confirm your Opik API key and workspace details. Ensure environment variables for LLM providers (e.g., `OPENAI_API_KEY`) are correctly set in the shell where your script runs.","message":"Authentication failures often occur due to incorrect API keys or workspace details. For cloud usage, ensure your API key has Agent Optimizer access.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For upgrades from Opik Helm chart version 1.9.39 or older, set `chartMigration.enabled: true` in your Helm upgrade command for the first migration, then set it back to `false` for subsequent upgrades.","message":"Opik's Helm chart has migrated from Bitnami charts and images to official Docker images. Bitnami's old public images are deprecated and hardened images are now subscription-based. This impacts self-hosted Kubernetes deployments.","severity":"deprecated","affected_versions":"<1.9.39 (for original Bitnami-based deployments)"}],"env_vars":null,"search_vec":"'1.11.1':49 'activ':54 'agent':39 'ai':70 'applic':24 'built':7 'capabl':33 'comet':9,71 'communiti':62 'community-driven':61 'comprehens':27 'current':46 'design':16 'develop':55 'driven':63 'entir':20 'evalu':5,29,67 'frequent':57 'languag':36 'larg':35 'lifecycl':21 'llm':2,23,65 'model':37 'monitor':30,68 'observ':3,66 'open':13 'open-sourc':12 'opik':1,6 'optim':32 'platform':15 'product':44 'prototyp':42 'provid':26 'roadmap':64 'sourc':14 'streamlin':18 'system':40 'trace':28,69 'updat':58 'version':47","created_at":"2026-04-09T18:46:33.524007+00:00","updated_at":"2026-04-16T17:47:08.179083+00:00","problems":[{"fix":"Set the `OPIK_API_KEY` environment variable or configure the SDK using `opik.configure(api_key=\"YOUR_API_KEY\")` in your code, or run `opik configure` in the terminal.","cause":"This error occurs when the Opik Python SDK attempts to connect to Opik Cloud without a configured API key, which is essential for authentication.","error":"OPIK_API_KEY is not set"},{"fix":"Pin the `pyrate-limiter` dependency to a 3.x release by running `pip install \"pyrate-limiter>=3.0.0,<4.0.0\"`.","cause":"This error arises from an incompatibility between Opik's optimizer and `pyrate-limiter` version 4.x, as that version removed a legacy flag used by Opik's optimizer.","error":"TypeError: Limiter.__init__() got an unexpected keyword argument 'raise_when_fail'"},{"fix":"Ensure your `pydantic-settings` and `pydantic` versions are compatible with `opik` and your Python environment. This might involve pinning specific versions of `pydantic` or `pydantic-settings` to resolve the conflict.","cause":"This indicates a version incompatibility, usually between the installed `pydantic-settings` library and other dependencies or the Python environment, often seen in Docker images with specific Python versions.","error":"ImportError: cannot import name 'ConfigFileSourceMixin' from 'pydantic_settings.sources'"},{"fix":"Ensure you are using the `ChatPrompt` class from `opik_optimizer` to define your prompt object before passing it to `optimize_prompt()`. Example: `from opik_optimizer import ChatPrompt; prompt = ChatPrompt(messages=[...], model=\"gpt-4\")`.","cause":"This error occurs when an incorrect type is passed to the `optimize_prompt()` method of Opik's optimizer, which specifically expects a `ChatPrompt` object.","error":"ValueError: Prompt must be a ChatPrompt object"},{"fix":"Verify that the Opik backend server is running and accessible from your environment, and ensure that `OPIK_URL_OVERRIDE` is correctly set to the backend's API endpoint. Running `opik configure` can help set up the correct environment variables.","cause":"This error typically indicates that the Opik SDK client is unable to send trace data (spans) to the Opik backend, often due to an incorrectly configured `OPIK_URL_OVERRIDE` or the Opik server not running or being inaccessible.","error":"OPIK: Failed to process CreateSpansBatchMessage."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.2.43","cli_name":"opik","cli_version":"opik, version 2.0.37","type":"library","homepage":"https://www.comet.com","github":"https://github.com/comet-ml/opik","docs":null,"changelog":null,"pypi":"https://pypi.org/project/opik/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["llm-agents","ai-ml","observability"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}