Contributing

OxiPulse is an open-source project and contributions are welcome. This guide explains how to set up a local development environment, run the agent, and submit a pull request.

Prerequisites

  • Rust (stable, edition 2024 or later)
  • Git
  • A Linux or macOS machine (Windows support for development is partial)

Local setup

Getting started
# Clone the repo
git clone https://github.com/securyblack/oxi-pulse.git
cd oxi-pulse

# Build in debug mode
cargo build

# Run the agent locally (set a dummy endpoint for testing)
OXIPULSE_ENDPOINT=http://localhost:4317 OXIPULSE_TOKEN=test cargo run

Project structure

Source tree
src/
├── main.rs          # Entry point, service loop
├── config/          # Config loading (env vars + TOML)
├── metrics/         # Metric collectors (cpu, ram, disk, net)
├── telemetry/       # OTLP export via gRPC
└── updater/         # Auto-update logic

Submitting a pull request

  1. Fork the repository on GitHub.
  2. Create a branch: git checkout -b feat/my-improvement
  3. Make your changes and ensure cargo build passes.
  4. Run cargo clippy -- -D warnings and fix any lint errors.
  5. Open a pull request against the main branch with a clear description.
Keep dependencies Apache-2.0 or MIT only. No GPL or LGPL dependencies are accepted. This is a hard requirement to keep the project commercially usable.

Security issues

Please do not open public GitHub issues for security vulnerabilities. Instead, report them privately via security@securyblack.com.

Commit conventions

We use conventional commits for clean release notes:

Commit format examples
feat: add disk I/O metrics
fix: prevent buffer overflow on large payloads
docs: update configuration reference
chore: bump opentelemetry-otlp to 0.14

Code of conduct

Be respectful. We follow the Contributor Covenant code of conduct.