Contributing to Opik

We're excited that you're interested in contributing to Opik! There are many ways to contribute, from writing code to improving the documentation.

The easiest way to get started is to:

Submit bug reports and feature requests
Review the documentation and submit Pull Requests to improve it
Speaking or writing about Opik and letting us know
Upvoting popular feature requests to show your support
Review our Contributor License Agreement

Submitting a new issue or feature request

Submitting a new issue

Thanks for taking the time to submit an issue, it's the best way to help us improve Opik!

Before submitting a new issue, please check the existing issues to avoid duplicates.

To help us understand the issue you're experiencing, please provide steps to reproduce the issue included a minimal code snippet that reproduces the issue. This helps us diagnose the issue and fix it more quickly.

Submitting a new feature request

Feature requests are welcome! To help us understand the feature you'd like to see, please provide:

A short description of the motivation behind this request
A detailed description of the feature you'd like to see, including any code snippets if applicable

If you are in a position to submit a PR for the feature, feel free to open a PR !

General Contribution Guidelines

Code Formatting and Style

When contributing to Opik, please follow these formatting and code style guidelines:

Avoid Excessive Formatting Changes

Do not apply formatting changes that drastically alter files without clear benefit. When submitting PRs:

Focus on meaningful changes: Only format code that you're actively modifying or fixing
Avoid mass reformatting: Don't run formatters across entire files or codebases unless specifically requested
Be intentional: If you need to apply formatting changes, ensure they serve a clear purpose (e.g., fixing consistency issues, improving readability)

When Formatting is Appropriate

Fixing inconsistent indentation in code you're modifying
Correcting style violations in files you're actively working on
Following project-specific linting rules (see component-specific sections below)
Addressing formatting issues flagged by CI/CD pipelines

When to Avoid Formatting

Applying auto-formatters to entire files when only changing a few lines
Changing whitespace, line endings, or indentation across large portions of unchanged code
Reformatting files just because your editor suggests it
Making stylistic changes that don't align with the existing codebase patterns

Remember: Code reviews should focus on logic, functionality, and meaningful improvements. Excessive formatting changes can obscure the actual purpose of your contribution and make reviews more difficult.

Project set up and Architecture

The Opik project is made up of five main sub-projects:

apps/opik-documentation: The Opik documentation website
deployment/installer: The Opik installer
sdks/python: The Opik Python SDK
apps/opik-frontend: The Opik frontend application
apps/opik-backend: The Opik backend server

In addition, Opik relies on:

Clickhouse: Used to trace traces, spans and feedback scores
MySQL: Used to store metadata associated with projects, datasets, experiments, etc.
Redis: Used for caching

Local Development Setup

We provide multiple development modes optimized for different workflows:

Quick Start Guide

Mode	Use Case	Command	Speed
Docker Mode	Full stack testing, closest to production	`./opik.sh --build`	Slow
Local Process	Fast BE + FE development with hot reload	`scripts/dev-runner.sh`	Fast
BE-Only	Backend development only	`scripts/dev-runner.sh --be-only-restart`	Fast
Infrastructure	Manual with IDE development	`./opik.sh --infra --port-mapping`	Medium

Docker Mode (Full Stack)

Best for testing the complete system or when you need an environment closest to production.

# Build and start all services (first time setup)
./opik.sh --build

# On Windows
.\opik.ps1 --build

# Start without rebuilding (faster for subsequent runs)
./opik.sh

# Check service health
./opik.sh --verify

# Stop all services
./opik.sh --stop

Access the UI at http://localhost:5173

Local Process Mode (Recommended for Development)

Best for rapid development with instant code reloading. Runs backend and frontend as local processes.

# Full restart (stop, build, start) - use this for first time or after major changes
scripts/dev-runner.sh

# On Windows
scripts\dev-runner.ps1

# Start without rebuilding (faster when no dependency changes)
scripts/dev-runner.sh --start

# Check status
scripts/dev-runner.sh --verify

# View logs
scripts/dev-runner.sh --logs

Access the UI at http://localhost:5174 (Vite dev server with hot reload)

BE-Only Mode (Backend Development)

Best for backend-focused work. Frontend runs in Docker, backend as a local process.

# Start BE-only mode
scripts/dev-runner.sh --be-only-restart

# On Windows
scripts\dev-runner.ps1 --be-only-restart

Access the UI at http://localhost:5173

Additional Commands

# Build backend only
scripts/dev-runner.sh --build-be

# Build frontend only
scripts/dev-runner.sh --build-fe

# Run database migrations
scripts/dev-runner.sh --migrate

# Lint code
scripts/dev-runner.sh --lint-be
scripts/dev-runner.sh --lint-fe

# Enable debug logging
scripts/dev-runner.sh --restart --debug

Getting Help

For a complete list of available commands and options, use the --help flag:

# Linux/Mac
./opik.sh --help
scripts/dev-runner.sh --help

# Windows
.\opik.ps1 --help
scripts\dev-runner.ps1 --help

For comprehensive documentation on local development, including troubleshooting, advanced usage, and workflow examples, see our Local Development Guide.

Contributing to the documentation

The documentation is made up of two main parts:

apps/opik-documentation/documentation: The Opik documentation website
apps/opik-documentation/python-sdk-docs: The Python reference documentation

Contributing to the documentation website

The documentation website is built with Fern and is located in apps/opik-documentation/documentation.

In order to run the documentation website locally, you need to have Node.js and npm installed. You can follow this guide to install Node.js and npm here.

Once installed, you can run the documentation locally using the following command:

cd apps/opik-documentation/documentation

# Install dependencies - Only needs to be run once
npm install

# Run the documentation website locally
npm run dev

You can then access the documentation website at http://localhost:3000. Any change you make to the documentation will be updated in real-time.

When updating the documentation, you will need to update either:

fern/docs: This is where all the markdown code is stored and where the majority of the documentation is located.
docs/cookbook: This is where all our cookbooks are located.

Contributing to the Python SDK reference documentation

The Python SDK reference documentation is built using Sphinx and is located in apps/opik-documentation/python-sdk-docs.

In order to run the Python SDK reference documentation locally, you need to have python and pip installed. Once installed, you can run the documentation locally using the following command:

cd apps/opik-documentation/python-sdk-docs

# Install dependencies - Only needs to be run once
pip install -r requirements.txt

# Run the python sdk reference documentation locally
make dev

The Python SDK reference documentation will be built and available at http://127.0.0.1:8000. Any change you make to the documentation will be updated in real-time.

Contributing to the Python SDK

Setting up your development environment:

In order to develop features in the Python SDK, you will need to have Opik running locally. Use the provided scripts to start the appropriate services:

On Linux or Mac:

# From the root of the repository
./opik.sh

# Configure the Python SDK to point to the local Opik deployment
opik configure --use_local

On Windows:

# From the root of the repository
powershell -ExecutionPolicy ByPass -c ".\opik.ps1"

# Configure the Python SDK to point to the local Opik deployment
opik configure --use_local

The Opik server will be running on http://localhost:5173.

Note for Windows users:

If Python is installed at system level, make sure C:\Users\<name>\AppData\Local\Programs\Python<version>\Scripts\ is added to your PATH for the opik command to work after installation, and restart your terminal.

It's recommended to use a virtual environment:

# Create a virtual environment
py -m venv <environment_name>

# Activate the virtual environment
cd <environment_name>\Scripts && .\activate.bat

# Install the SDK
pip install -e sdks/python

# Configure the SDK
opik configure --use_local

Submitting a PR:

First, please read the coding guidelines for our Python SDK.

The Python SDK is available under sdks/python and can be installed locally using pip install -e sdks/python.

Testing your changes:

For most SDK contributions, you should run the e2e tests which validate the core functionality:

cd sdks/python

# Install the test requirements
pip install -r tests/test_requirements.txt
pip install -r tests/unit/test_requirements.txt

# Install pre-commit for linting
pip install pre-commit

# Run the e2e tests
pytest tests/e2e

If you're making changes to specific integrations (openai, anthropic, etc.):

Install the integration-specific requirements:

# Example for OpenAI integration
pip install -r tests/integrations/openai/requirements.txt

Configure any necessary API keys for the integration

Run the specific integration tests:

# Example for OpenAI integration
pytest tests/integrations/openai

Before submitting a PR, please ensure that your code passes the linter:

cd sdks/python
pre-commit run --all-files

Note

If you changes impact public facing methods or docstrings, please also update the documentation. You can find more information about updating the docs in the documentation contribution guide.

Contributing to the frontend

The Opik frontend is a React application located in apps/opik-frontend.

Prerequisites

Ensure you have Node.js installed.

Quick Start

For rapid development with hot reload, use the local process mode:

# Linux/Mac - restart everything
scripts/dev-runner.sh

# Or just start (faster if already built)
scripts/dev-runner.sh --start

# Windows
scripts\dev-runner.ps1

Access the UI at http://localhost:5174 (Vite dev server with hot reload)

Alternative Setup Methods

You can also use:

Docker Mode: ./opik.sh --build for a complete Docker-based environment
Manual Setup: ./opik.sh --backend --port-mapping then manually start the frontend

For detailed setup instructions for each mode, see our Frontend Contribution Guide.

Code Formatting

Before submitting a PR, ensure your code passes all checks:

# Linting (recommended)
scripts/dev-runner.sh --lint-fe  # Linux/Mac
scripts\dev-runner.ps1 --lint-fe  # Windows

# Or manually
cd apps/opik-frontend
npm run lint
npm run typecheck # TypeScript type checking

Testing

cd apps/opik-frontend
npm run test # Unit tests for utilities and helpers

Contributing to the backend

The Opik backend is a Java application located in apps/opik-backend.

Prerequisites

Ensure you have Java and Maven installed.

Quick Start

For rapid backend development with a local process:

# Linux/Mac - restart everything
scripts/dev-runner.sh --be-only-restart

# Or just start (faster if already built)
scripts/dev-runner.sh --be-only-start

# Windows
scripts\dev-runner.ps1 --be-only-restart

Access the backend API at http://localhost:8080

Alternative Setup Methods

You can also use:

Docker Mode: ./opik.sh --build for a complete Docker-based environment
Manual Setup: ./opik.sh --infra --port-mapping then manually build and start the backend

For detailed setup instructions for each mode, see our Backend Contribution Guide.

Code Formatting and Testing

Before submitting a PR, ensure your code is formatted. Our CI will check and fail if it is not formatted. Use the following command:

# Code formatting (recommended)
scripts/dev-runner.sh --lint-be  # Linux/Mac
scripts\dev-runner.ps1 --lint-be  # Windows

# Or manually
cd apps/opik-backend
mvn spotless:apply

Testing

# Run tests
mvn test

Tests leverage the testcontainers library to run integration tests against a real instances of the external services. Ports are randomly assigned by the library to avoid conflicts.

Health checks

To see your applications health enter url http://localhost:8080/healthcheck

Database Migrations

To run database migrations:

# Using dev-runner (recommended)
scripts/dev-runner.sh --migrate  # Linux/Mac
scripts\dev-runner.ps1 --migrate  # Windows

# Or manually
cd apps/opik-backend
java -jar target/opik-backend-*.jar db migrate config.yml          # MySQL
java -jar target/opik-backend-*.jar dbAnalytics migrate config.yml # ClickHouse

For detailed information on migrations, health checks, and advanced topics, see our Backend Contribution Guide.

Accessing Clickhouse

You can curl the ClickHouse REST endpoint with echo 'SELECT version()' | curl -H 'X-ClickHouse-User: opik' -H 'X-ClickHouse-Key: opik' 'http://localhost:8123/' -d @-.

SHOW DATABASES

Query id: a9faa739-5565-4fc5-8843-5dc0f72ff46d

┌─name───────────────┐
│ INFORMATION_SCHEMA │
│ opik               │
│ default            │
│ information_schema │
│ system             │
└────────────────────┘

5 rows in set. Elapsed: 0.004 sec.

Sample result: 23.8.15.35

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to Opik

Submitting a new issue or feature request

Submitting a new issue

Submitting a new feature request

General Contribution Guidelines

Code Formatting and Style

Avoid Excessive Formatting Changes

When Formatting is Appropriate

When to Avoid Formatting

Project set up and Architecture

Local Development Setup

Quick Start Guide

Docker Mode (Full Stack)

Local Process Mode (Recommended for Development)

BE-Only Mode (Backend Development)

Additional Commands

Getting Help

Contributing to the documentation

Contributing to the documentation website

Contributing to the Python SDK reference documentation

Contributing to the Python SDK

Contributing to the frontend

Prerequisites

Quick Start

Alternative Setup Methods

Code Formatting

Testing

Contributing to the backend

Prerequisites

Quick Start

Alternative Setup Methods

Code Formatting and Testing

Testing

Health checks

Database Migrations

Accessing Clickhouse