Same agent Smaller bill. The tools and infrastructure to get more work from your AI. Fewer tokens. Less compute. Lower cost.
Contributing to OpenLIT
Thanks for helping improve OpenLIT. Contributions of code, documentation, bug reports, and integration feedback are all welcome.
Before you start
- Read the README and the applicable component README for setup.
- Read AGENTS.md for repository-wide engineering and CE/OSS boundaries.
- For a substantial change, open or discuss an issue first so maintainers can confirm the scope. Small documentation fixes can go straight to a pull request.
- Follow the Code of Conduct.
Run OpenLIT locally
One script runs the UI (next dev), the OTLP receiver, the realtime engine,
and NATS JetStream together, and starts ClickHouse in Docker if none is
running. You need Node.js 20+, Go 1.25+, Docker with Compose v2.24+, curl,
openssl, and lsof.
cd src/client
npm install
cp .env.example .env # set NEXTAUTH_SECRET, NEXTAUTH_URL, SQLITE_DATABASE_URL=file:./data.db
cd ../..
SEED=1 scripts/dev-realtime.sh # first run: also creates the default user
scripts/dev-realtime.sh # later runs
Open http://localhost:3000 and sign in with [email protected] /
openlituser. Ctrl+C stops every service. To exercise alerts, create an API
key under Settings → API Keys and send sample spans:
OPENLIT_API_KEY=<your key> scripts/dev-realtime-send-spans.py --count 20 --error-rate 1
See Local development for options, running the UI on its own, and troubleshooting, and src/README.md for the Docker Compose development stack.
Development workflow
Fork the repository and clone your fork.
git clone https://github.com/YOUR_USERNAME/openlit.git cd openlitCreate a focused branch.
git switch -c fix/short-descriptionMake the change, including tests and documentation when they are relevant. Keep unrelated formatting and refactors out of the pull request.
Run the focused checks for the component you changed. For client changes, run at least:
cd src/client npm run lint npx tsc --noEmit npm testFor the OTLP receiver or the realtime engine (
src/otlp-receiver,src/engine):gofmt -l . && go vet ./... && go test ./...The relevant README, package scripts, and CI workflow describe additional component-specific checks.
Commit with a clear subject, push your branch, and open a pull request against
main. PR titles must use Conventional Commit form, for examplefeat: add trace filtersorfix(client): handle empty projects.git commit -m "fix: describe the change" git push origin fix/short-description
Pull requests
- Explain the problem and the solution; link the related issue when one exists.
- Use a title in the form
type: concise lowercase summaryortype(scope): concise lowercase summary. Allowed types arefeat,fix,docs,chore,refactor,test,ci,build,perf,style, andrevert. - Include tests for behavior changes and update user-facing documentation.
- Rebase or merge the current
mainbefore requesting review if your branch is behind. - Complete the pull-request template honestly. Maintainers may ask for changes to keep a contribution safe, focused, and maintainable.
Issues and questions
Search existing issues before opening a new one. Bug reports should include reproducible steps, expected and actual behavior, and relevant non-sensitive logs. For feature ideas or general questions, use GitHub Issues or the community links in the README.
Do not report security vulnerabilities in a public issue; follow SECURITY.md instead.