o11y/docs/contributing/development.md

Development Guide

Welcome! This guide will help you set up your local development environment for Hanzo O11y. Let's get you started! 🚀

What do I need?

Before diving in, make sure you have these tools installed:

• Git - Our version control system

  • Download from git-scm.com

• Go - Powers our backend

  • Download from go.dev/dl
  • Check go.mod for the minimum version

• Node - Powers our frontend

  • Download from nodejs.org
  • Check .nvmrc for the version

• Pnpm - Our frontend package manager

  • Follow the installation guide

• Docker - For running Datastore and Postgres locally

  • Get it from docs.docker.com/get-docker

💡 Tip: Run make help to see all available commands with descriptions

How do I get the code?

1. Open your terminal
2. Clone the repository:

   git clone https://github.com/Hanzo O11y/o11y.git
   

3. Navigate to the project:

   cd o11y
   

How do I run it locally?

Hanzo O11y has three main components: Datastore, Backend, and Frontend. Let's set them up one by one.

1. Setting up Datastore

First, we need to get Datastore running:

make devenv-datastore

This command:

• Starts Datastore in a single-shard, single-replica cluster
• Sets up Zookeeper
• Runs the latest schema migrations

2. Setting up Hanzo O11y OpenTelemetry Collector

Next, start the OpenTelemetry Collector to receive telemetry data:

make devenv-otel-collector

This command:

• Starts the Hanzo O11y OpenTelemetry Collector
• Listens on port 4317 (gRPC) and 4318 (HTTP) for incoming telemetry data
• Forwards data to Datastore for storage

💡 Quick Setup: Use make devenv-up to start both Datastore and OTel Collector together

3. Starting the Backend

1. Run the backend server:

   make go-run-community
   

2. Verify it's working:

   curl http://localhost:8080/v1/o11y/health
   

   You should see: {"status":"ok"}

💡 Tip: The API server runs at http://localhost:8080/ by default

4. Setting up the Frontend

1. Navigate to the frontend directory:

   cd frontend
   

2. Install dependencies:

   pnpm install
   

3. Create a .env file in this directory:

   VITE_FRONTEND_API_ENDPOINT=http://localhost:8080
   

4. Start the development server:

   pnpm dev
   

💡 Tip: pnpm dev will automatically rebuild when you make changes to the code

Now you're all set to start developing! Happy coding! 🎉

Verifying Your Setup

To verify everything is working correctly:

1. Check Datastore: curl http://localhost:8123/ping (should return "Ok.")
2. Check OTel Collector: curl http://localhost:13133 (should return health status)
3. Check Backend: curl http://localhost:8080/v1/o11y/health (should return {"status":"ok"})
4. Check Frontend: Open http://localhost:3301 in your browser

How to send test data?

You can now send telemetry data to your local Hanzo O11y instance:

• OTLP gRPC: localhost:4317
• OTLP HTTP: localhost:4318

For example, using curl to send a test trace:

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -d '{"resourceSpans":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"test-service"}}]},"scopeSpans":[{"spans":[{"traceId":"12345678901234567890123456789012","spanId":"1234567890123456","name":"test-span","startTimeUnixNano":"1609459200000000000","endTimeUnixNano":"1609459201000000000"}]}]}]}'