openobserve/CONTRIBUTING.md

Contributing to Zinc Observe

Setting up development environment

Prerequisite

Zinc Observe uses Rust & embded sled db (For server) & VueJS (For Web UI)

You must have follwing installed:

1. Git
2. Rust & Cargo 1.61.0 + (We recommend 1.66+),
3. nodejs v14+ and npm v6+

Building from source code

Lets clone the repo and get started

git clone https://github.com/zinclabs/zinc-observe
cd zinc-observe

Now let's build the UI

cd web
npm install
npm run build
cd ..

Output will be stored in web/dist folder. web/dist will be embedded in zinc-observe binary when zinc-observe application is built.

It is important that you build the web app every time you make any changes to javascript code as the built code is then embedded in zinc-observe application.

Time to build the rust application now

Make sure you are in zinc-observe directory & not in zinc-observe/web

Simple:

cargo build --release # will build the zinc-observe binary

Developing

Once you have the source code cloned you can start development.

There are 2 areas of development.

1. UI
2. Server

Server

cargo run 

Please note by default user 'admin' with password 'Complexpass#123' is created

This will start the zinc-observe API server on port 5080

environment variables ZO_USER_NAME and ZO_USER_PASSWORD can be used first time to configure default admin user when zinc-observe is started.

UI

If not alredy present create .env file in web directory & set VITE_ZINC_ENL_ENDPOINT=http://localhost:5080

cd web
npm install
npm run dev

This will start UI server on port 8080 , to change port specify it in vite.config.ts

In order for you to effectively use the UI you would want to have the Zinc-Observe API server running in a seperate window that will accept requests from the UI.

Swagger

The server also exposes a Swagger API endpoint which you can see by visiting the /swagger/index.html path. It uses utoipa to mark API endpoints with comment annotations & to generate the API spec from the annotations to Swagger Documentation 2.0.

Build docker image

Make sure that you have docker.

Simple build:

docker build -t zinc-observe:latest-amd64 -f deploy/build/Dockerfile .

Multi-arch build

In order to build multi-arch builds you will need buildx installed. You will need to pass the platform flag for the platform that you want to build.

docker build -t zinc-observe:latest-amd64 -f deploy/build/Dockerfile.tag.amd64 .

Please check folder deploy/build for docker files.

Checks in CI pipeline

We check for following in CI pipeline for any pull requests.

1. Unit test code coverage for rust code.
   • If code coverage is less than 81% the CI tests will fail.
   • You can test coverage yourself by running ./coverage.sh
   • We use cargo-llvm-covfor code generating coverage to generate report in .json format.
   • Run 'cargo llvm-cov --lcov --output-path lcov.info' to genrate report & use Coverage Gutters with VS code for visualizing code coverage.
   • You can also generate html report by using 'cargo llvm-cov --html' to generate html report in target/debug/llvm-cov/html/index.html
2. Linting in Javascript for GUI
   • We run eslint for javacript anf any linting failures will result in build failures.
   • You can test for linting failures by running ./eslint.sh in web folder.

How to contribute code

1. Fork the repository on github (e.g. awesomedev/zinc-observe)
2. Clone the repo from the forked repository ( e.g. awesomedev/zinc-observe) to your machine.
3. create a new branch locally.
4. Make the changes to code.
5. Push the code to your repo.
6. Create a PR
7. Make sure that the automatic CI checks pass for your PR.