Log LLM and agent traces to Comet Opik with the @track decorator, on Comet Cloud or a self-hosted deployment

Documented steps

1. Install the SDK: pip install opik (Python) or npm install opik (TypeScript, unscoped package name).
2. Decide on hosting: Comet-hosted cloud (sign up at comet.com/opik, default API URL https://www.comet.com/opik/api) or self-hosted.
3. For cloud, run opik configure and supply your API key and workspace interactively, or set OPIK_API_KEY and OPIK_WORKSPACE as environment variables. Add --yes for non-interactive CI use.
4. For a local self-hosted instance: git clone https://github.com/comet-ml/opik.git && cd opik && ./opik.sh. The UI and API come up at http://localhost:5173. This requires Docker and Docker Compose.
5. For production self-hosting, use the Kubernetes deployment guide at comet.com/docs/opik/self-host/kubernetes instead of opik.sh.
6. Point the SDK at a local instance with opik configure --use_local or opik.configure(use_local=True). For any other custom URL, set OPIK_URL_OVERRIDE.
7. Verify connectivity and configuration with opik healthcheck before writing code.
8. Instrument functions with the decorator: from opik import track, then @track (bare) or @track(type='llm', tags=[...], metadata={...}). Documented parameters are type (general, tool, llm, guardrail), tags, metadata, capture_input, ignore_arguments, capture_output, generations_aggregator, flush, project_name, create_duplicate_root_span, entrypoint, source, and environment.
9. Nested decorated calls are captured automatically as nested spans under the enclosing trace; no manual wiring is needed.
10. For finer control use context managers: with opik.start_as_current_trace('name', project_name='proj') as trace: trace.input = {...}; trace.output = {...}; trace.tags = [...]; trace.metadata = {...}.
11. From non-decorator flows use the low-level client: Opik(api_url=..., api_key=..., project_name=...), then client.trace(...), trace.span(...), and client.flush() before exit.
12. Prefer a prebuilt integration over manual instrumentation where one exists. Confirmed integrations include LangChain, LangGraph, LlamaIndex, CrewAI, DSPy, Haystack, Agno, AG2/Autogen, Smolagents, Pydantic AI, Semantic Kernel, Strands Agents, OpenAI Agents, Google ADK, Claude Agent SDK, and Temporal; providers OpenAI, Anthropic, Bedrock, Gemini, Groq, Mistral, Ollama, WatsonX, and xAI; TypeScript LangChain, Mastra, and the Vercel AI SDK; and gateways LiteLLM, Portkey, Helicone, and the Vercel AI Gateway.
13. Route traces into a specific project with the project_name argument per trace or the OPIK_PROJECT_NAME environment variable globally.
14. In tests and CI, set OPIK_TRACK_DISABLE=true to turn tracking off entirely rather than stripping decorators.
15. Other documented environment variables worth knowing: OPIK_DEFAULT_FLUSH_TIMEOUT, OPIK_CHECK_TLS_CERTIFICATE, OPIK_CONFIG_PATH, OPIK_CONSOLE_LOGGING_LEVEL, OPIK_ENVIRONMENT, and OPIK_SENTRY_ENABLE.