Contributing to SigNoz

System Architecture Overview

SigNoz is an OpenTelemetry-native observability platform. Telemetry flows from instrumented apps → OTel Collector → ClickHouse → Go backend → React frontend. All backend services are packaged as a single binary.

Core Components

Frontend Architecture

React 18 TypeScript SPA built with Webpack. Ant Design components, Redux for global state, React Query for server data. All pages lazy-loaded. RBAC enforced at route and component level.

Backend Architecture

Single Go 1.24 binary. API server exposes :8080 (public) and :8085 (private). The provider pattern is used throughout — each subsystem is a typed interface with pluggable implementations wired via pkg/signoz.

Data Flow Pipeline

Repository Structure

signoz/
├── frontend/                   # React 18 TypeScript SPA
│   ├── src/
│   │   ├── AppRoutes/          # Routes, PrivateRoute, RBAC guards
│   │   ├── api/                # API client functions
│   │   ├── components/         # Reusable UI components
│   │   ├── container/          # AppLayout, SideNav, TopNav
│   │   ├── providers/          # Context: App, Dashboard, QueryBuilder
│   │   └── store/              # Redux store
│   └── src/container/OnboardingV2Container/onboarding-configs/
│       └── onboarding-config-with-links.json  # New Source / Get Started config
│
├── pkg/query-service/          # OSS Go backend
│   └── app/
│       ├── clickhouseReader/   # All ClickHouse reads (interfaces.Reader)
│       ├── http_handler.go     # HTTP route handlers
│       └── server.go           # Server struct, :8080/:8085
│
├── pkg/                        # Shared Go packages (OSS)
│   ├── apiserver/signozapiserver/  # Route registration, OpenAPI defs
│   ├── errors/                 # Structured error package
│   ├── factory/                # Provider + Service lifecycle
│   ├── flagger/                # Feature flag system (OpenFeature)
│   ├── modules/                # Business logic modules (user, session, org)
│   ├── signoz/                 # IoC container — wires all providers
│   ├── sqlstore/               # SQL abstraction (Bun ORM, PostgreSQL/SQLite)
│   └── types/                  # Shared domain types
│
├── ee/query-service/           # Enterprise-only features (never import from pkg/)
├── .devenv/docker/clickhouse/  # Local dev ClickHouse compose
├── deploy/docker/              # Docker Compose (standalone + HA)
├── tests/integration/          # Python/pytest integration tests
├── docs/api/openapi.yml        # Auto-generated OpenAPI spec
├── docs/contributing/         # This guide's source files
└── go.mod                      # Go 1.24.0, 300+ deps

Development Environment Setup

SigNoz has three main components you need to run locally: ClickHouse, Backend, and Frontend. Run make help to see all available Make commands.

Prerequisites

git clone https://github.com/SigNoz/signoz.git && cd signoz

1 — Start ClickHouse

# Starts ClickHouse single-shard single-replica + Zookeeper + schema migrations
make devenv-clickhouse

# Start OTel Collector (listens :4317 gRPC, :4318 HTTP)
make devenv-signoz-otel-collector

# Or start both at once
make devenv-up

# Verify
curl http://localhost:8123/ping          # → Ok.
curl http://localhost:13133             # → OTel Collector health

2 — Run the Backend

# OSS build (runs on :8080)
make go-run-community

# Verify
curl http://localhost:8080/api/v1/health   # → {"status":"ok"}

3 — Run the Frontend

cd frontend
yarn install
# Create .env
echo "VITE_FRONTEND_API_ENDPOINT=http://localhost:8080" > .env
yarn dev    # starts on :3301 with HMR, auto-rebuilds on change

Sending Test Data

# OTLP gRPC: localhost:4317 | OTLP HTTP: localhost:4318
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"}]}]}]}'

Deployment Options

Go Backend — Contributing Standards

Packages

All shared Go code lives under pkg/. Each package represents a distinct domain concept with a clear public interface.

Import Groups

import (
    // 1. Standard library
    "fmt"
    "net/http"

    // 2. External dependencies
    "github.com/gorilla/mux"

    // 3. Internal
    "github.com/SigNoz/signoz/pkg/errors"
)

Abstractions

Every exported type, interface, or wrapper is a permanent commitment. Before introducing one, answer four questions in your PR description:

1. What already exists? Name the specific type/function that covers this today.
2. What does the new abstraction add? Name the concrete capability. "Cleaner" or "more reusable" are insufficient.
3. What does it drop? List what it cannot represent. Every gap must be justified or error-handled.
4. Who consumes it? List all call sites. One producer + one consumer = you need a function, not a type.

When a new type IS warranted

• Serialization boundary — must be persisted, sent over wire, or written to config.
• Invariant enforcement — constructor/methods enforce constraints raw data doesn't carry.
• Multiple distinct consumers — 3+ call sites use it in meaningfully different ways.
• Dependency firewall — lives in lightweight package so consumers avoid heavy import.

Errors

SigNoz has its own structured error package at pkg/errors. Always use it instead of the standard library.

// Instead of errors.New() or fmt.Errorf():
errors.New(typ, code, message)
errors.Newf(typ, code, message, args...)
errors.Wrapf(err, typ, code, message)   // adds context, preserves original

Provider Pattern

Providers are the dependency injection mechanism. They adapt external services and deliver functionality to the application. Think of them as typed, configurable adapters wired together in pkg/signoz.

Anatomy of a provider

Wiring (3 steps in pkg/signoz)

// 1. Add config to pkg/signoz/config.go
type Config struct {
    MyProvider myprovider.Config `mapstructure:"myprovider"`
}

// 2. Register factory in pkg/signoz/provider.go
func NewMyProviderFactories() factory.NamedMap[...] {
    return factory.MustNewNamedMap(myproviderone.NewFactory())
}

// 3. Instantiate in pkg/signoz/signoz.go SigNoz struct
myprovider, err := myproviderone.New(ctx, settings, config.MyProvider, "one/two")

Service Lifecycle

A service is a component with a managed lifecycle: it starts, runs for the application's lifetime, and stops gracefully. Services are distinct from providers — a provider adapts an external dependency; a service has its own lifecycle tied to the application.

The factory.Service interface

type Service interface {
    Start(context.Context) error  // MUST BLOCK until stopped or error
    Stop(context.Context) error   // causes Start to unblock
}

Shutdown coordination — always use stopC

// Constructor
stopC: make(chan struct{})

// Start: block
<-provider.stopC

// Stop: unblock
close(provider.stopC)

Wiring to the registry

registry, err := factory.NewRegistry(
    instrumentation.Logger(),
    factory.NewNamedService(factory.MustNewName("myservice"), myService),
    // ... more services
)
// Registry calls Start on all services concurrently.
// Any Start error triggers application shutdown.
// Stop is called on all services concurrently at shutdown.

HTTP Handlers

Handlers are thin adapters — they decode HTTP requests, call the appropriate module, and return structured responses. Business logic belongs in modules (pkg/modules/user, pkg/modules/session, etc.), not in handlers.

Typical handler implementation

func (h *handler) CreateThing(rw http.ResponseWriter, req *http.Request) {
    claims, err := authtypes.ClaimsFromContext(req.Context())
    if err != nil { render.Error(rw, err); return }

    var in types.PostableThing
    if err := binding.JSON.BindBody(req.Body, &in); err != nil {
        render.Error(rw, err); return
    }

    out, err := h.module.CreateThing(req.Context(), claims.OrgID, &in)
    if err != nil { render.Error(rw, err); return }

    render.Success(rw, http.StatusCreated, out)
}

Registering a route in signozapiserver

if err := router.Handle("/api/v1/things", handler.New(
    provider.authZ.AdminAccess(provider.thingHandler.CreateThing),
    handler.OpenAPIDef{
        ID:                "CreateThing",
        Tags:              []string{"things"},
        Summary:           "Create thing",
        Description:       "This endpoint creates a thing",
        Request:           new(types.PostableThing),
        RequestContentType: "application/json",
        Response:          new(types.GettableThing),
        SuccessStatusCode: http.StatusCreated,
        ErrorStatusCodes:  []int{http.StatusBadRequest, http.StatusConflict},
        SecuritySchemes:   newSecuritySchemes(types.RoleAdmin),
    },
)).Methods(http.MethodPost).GetError(); err != nil {
    return err
}

// After adding a new endpoint, regenerate the OpenAPI spec:
// go run cmd/enterprise/*.go generate openapi

OpenAPI schema tags

Endpoint Design

Think of endpoint structure like navigating a file system. Resources should be pluralized and hierarchical.

POST   /v1/organizations          # Create
GET    /v1/organizations/:id       # Get by ID
PUT    /v1/organizations/:id       # Update
DELETE /v1/organizations/:id       # Delete
GET    /v1/organizations/:id/users # Nested resource
GET    /v1/organizations/me/users  # me = resolved via auth context

Feature Flags (Flagger)

Flagger is built on OpenFeature (CNCF). Three components: Registry (pkg/flagger/registry.go) — all available flags and defaults. Flagger (pkg/flagger/flagger.go) — consumer interface. Providers (pkg/flagger/<provider>flagger/) — supply override values.

Adding a new flag (2 steps)

// Step 1: Register in pkg/flagger/registry.go
var FeatureMyNewFeature = featuretypes.MustNewName("my_new_feature")

// Add to MustNewRegistry():
&featuretypes.Feature{
    Name:           FeatureMyNewFeature,
    Kind:           featuretypes.KindBoolean,
    Stage:          featuretypes.StageStable,
    Description:    "Controls whether my new feature is enabled",
    DefaultVariant: featuretypes.MustNewName("disabled"),
    Variants:       featuretypes.NewBooleanVariants(),
}

// Step 2 (optional): Override in config
// flagger.config.boolean.my_new_feature: true

Evaluating flags

evalCtx := featuretypes.NewFlaggerEvaluationContext(orgID)

// With error handling
enabled, err := flagger.Boolean(ctx, flagger.FeatureMyNewFeature, evalCtx)

// Non-critical — returns false on error and logs
if flagger.BooleanOrEmpty(ctx, flagger.FeatureMyNewFeature, evalCtx) { ... }

SQL & Database Patterns

SigNoz uses Bun ORM (pkg/sqlstore) against PostgreSQL or SQLite. The schema follows a star schema with organizations as the central entity — all other tables link to it via org_id foreign key.

type Thing struct {
    bun.BaseModel
    ID            types.Identifiable  `bun:",embed"`
    SomeColumn    string              `bun:"some_column"`
    TimeAuditable types.TimeAuditable `bun:",embed"`
    OrgID         string              `bun:"org_id"`
}

// Read
err := sqlstore.BunDBCtx(ctx).NewSelect().Model(thing).Where("id = ?", id).Scan(ctx)

// Transactions across multiple operations
err := sqlstore.RunInTxCtx(ctx, func(ctx context.Context) error { ... })

Migration rules

• Never use ON CASCADE — handle deletion in application logic.
• Never import from pkg/types inside migrations — define local types so migrations stay stable as types evolve.
• No Down migrations for now — leave the function empty.
• Always write idempotent migrations.
• Dialect-specific migrations go in the SQLDialect interface, not inline.
• All tables must have id, created_at, updated_at, and org_id (with FK to organizations), unless it's a transitive entity.

Query Range v5 — Design Principles

The Central Type: TelemetryFieldKey

Every filter, aggregation, group-by, order-by, and select is expressed in terms of TelemetryFieldKey. It is identified by three dimensions: Name, FieldContext (resource / attribute / span / log / body), and FieldDataType.

The Abstraction Stack (must never be bypassed)

StatementBuilder          ← orchestrates into executable SQL
  ├── AggExprRewriter     ← rewrites aggregation expressions
  ├── ConditionBuilder    ← builds WHERE predicates
  └── FieldMapper         ← TelemetryFieldKey → ClickHouse column

Inviolable Rules

Finding Issues to Work On

Pull Request Workflow

git checkout main && git pull && git checkout -b feat/my-feature

yarn test && go test ./...

For large contributions, split: (1) Structure — interfaces, types, configs. (2) Core implementation. (3) Docs + e2e tests.

Commit Convention

SigNoz follows Conventional Commits.

type(scope): short description

# Optional body (wrap at 72 chars)
Closes #1234

Testing Guide

Frontend

yarn test                           # all unit tests
yarn test:coverage                  # with coverage report
yarn test --watch src/components/X  # watch mode

Co-locate tests: ComponentName.test.tsx or __tests__/. Use React Testing Library — test behaviour, not implementation.

Backend

go test ./...                        # all unit tests
go test -v ./pkg/query-service/...  # verbose
go test -run TestQueryBuilder ./... # specific test
golangci-lint run ./...              # lint

Integration Tests

Python/pytest framework in tests/integration/ runs against real ClickHouse, PostgreSQL, and Zookeeper via testcontainers. Wiremock provides service doubles.

cd tests/integration && uv sync

uv run pytest --basetemp=./tmp/ -vv --reuse src/bootstrap/setup.py::test_setup

uv run pytest --basetemp=./tmp/ -vv --teardown -s src/bootstrap/setup.py::test_teardown

Running tests

uv run pytest --basetemp=./tmp/ -vv --reuse src/              # all
uv run pytest --basetemp=./tmp/ -vv --reuse src/querier/      # suite
uv run pytest --basetemp=./tmp/ -vv --reuse src/auth/01_register.py::test_register  # single

Key rules

• Always use --reuse when writing tests — avoids recreating the environment.
• Always use --teardown when done — avoids resource leaks.
• Prefix new test files with two-digit numbers (04_, 05_) for execution order.
• Each suite must complete in under 10 minutes.
• Test both success and failure scenarios. Use descriptive test names.

Frontend Code Standards

Adding a New Data Source (Onboarding)

The onboarding "New Source / Get Started" flow is configured via JSON at frontend/src/container/OnboardingV2Container/onboarding-configs/onboarding-config-with-links.json.

Required fields per data source object

Checklist before submitting

• SVG logo exists in public/Logos/ and has been optimized (npx svgo public/Logos/your-logo.svg).
• Use internalRedirect: true only for internal app routes (/integrations?...), not for docs links.
• Keys use kebab-case. Pattern: {service}-{subtype}-{action}.
• Test locally at http://localhost:3301/get-started-with-signoz-cloud — verify the data source appears, search works, links redirect correctly, and questions show correct help text.
• Tags must include at least one value; use existing tags when possible.
• relatedSearchKeywords — include name variations, lowercase, alphabetically sorted.

Other Repositories

Each repo has its own CONTRIBUTING.md. Always check it before submitting PRs.

Community & Getting Help

SigNoz Contributor Guide · Sources: docs/contributing/, docs/contributing/go/ (10 files), docs/api/openapi.yml · March 2026