āĻ¸ā§āĻ•āĻŋāĻĒ āĻ•āĻ°ā§‡ āĻŽā§‚āĻ˛ āĻ•āĻ¨ā§āĻŸā§‡āĻ¨ā§āĻŸ āĻ āĻ¯āĻžāĻ¨

🧠 Theory & Prerequisites

SigNoz Data Graph

Before installing SigNoz, you need to understand a few concepts and verify your system is ready. This chapter covers both the "why" and the "how to check."

📚 Core Observability Concepts​

1. Logs​

Plain text messages your app writes, like:

[2026-03-25 10:01:22] ERROR: Database connection failed
[2026-03-25 10:01:23] INFO: Retrying connection...

SigNoz collects these from PM2, Docker, or any log file.

2. Metrics​

Numbers measured over time — CPU %, request count, memory used, response time in ms.

Examples:

  • http_requests_total = 1523
  • cpu_usage = 67%
  • memory_used = 4.2 GiB

SigNoz plots these as graphs.

3. Traces​

A trace follows one user request as it travels through your system.

Example flow:

User clicks "Login"
  → API receives request        [20ms]
    → Validates token           [5ms]
      → Queries database        [80ms]
        → Returns response      [3ms]
Total: 108ms

Each step is a span. All spans together form a trace. SigNoz shows you the full timeline so you can spot slowdowns.

🔌 Understanding Ports (Very Important)​

A port is like a door number on your server. Each service needs its own unique port. Two services cannot share the same port.

How to Check If a Port Is Already In Use​

On Linux / Ubuntu (recommended):

sudo ss -ltnp | grep ':3301'
sudo ss -ltnp | grep ':4317'
sudo ss -ltnp | grep ':4318'
sudo ss -ltnp | grep ':8080'

Or check all SigNoz ports at once:

sudo ss -ltnp | egrep ':(3301|4317|4318|8080)\b' || echo "None of these ports in use"

On Linux (older systems using netstat):

sudo netstat -tlnp | grep ':3301'

On Windows (PowerShell):

netstat -ano | findstr ":3301"
netstat -ano | findstr ":4317"
netstat -ano | findstr ":8080"

On macOS:

lsof -i :3301
lsof -i :4317

đŸŸĸ No output = port is free (good — you can use it) 🔴 Output shown = port is in use (you must pick a different port)

Port Conflict Example — Real Case​

In our GCP VM, Jenkins was already using port 8080 (SigNoz's default UI port). Running SigNoz on 8080:8080 would have broken Jenkins. The fix: map SigNoz's internal 8080 to host port 3301 instead.

# WRONG (conflict with Jenkins)
- "8080:8080"

# CORRECT (SigNoz UI on 3301)
- "3301:8080"

đŸ’ģ System Requirements​

Minimum (Development / Testing)​

ResourceMinimum
CPU2 vCPU
RAM4 GB (6+ GB recommended)
Disk20 GB free
OSUbuntu 20.04+ / Debian 11+
ResourceRecommended
CPU4+ vCPU
RAM8+ GB
Disk50+ GB (telemetry data grows fast)
OSUbuntu 22.04 LTS

⚠ī¸ Our GCP VM had 7.7 GiB RAM with many other services already running. After adding SigNoz, only ~1.3 GiB was free. Monitor memory closely in shared environments.

🛠ī¸ Required Software​

1. Docker​

Check if installed:

docker --version

Install on Ubuntu/Debian (Linux):

sudo apt update
sudo apt install -y docker.io
sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker $USER   # so you don't need sudo every time
newgrp docker                   # apply group change in current session

Install on Windows: Download Docker Desktop

Install on macOS:

brew install --cask docker

2. Docker Compose​

Check if installed:

docker compose version

On modern Docker Desktop (Windows/Mac) and recent Docker installs on Linux, Compose is built in. If docker compose doesn't work, try docker-compose (old plugin style).

Install on Ubuntu (if missing):

sudo apt install -y docker-compose-plugin

3. Git​

Check if installed:

git --version

Install on Ubuntu:

sudo apt install -y git

Install on Windows: Download from git-scm.com

📋 Pre-Installation Checklist​

Run through this before starting the install:

# 1. Check Docker
docker --version

# 2. Check Docker Compose
docker compose version

# 3. Check Git
git --version

# 4. Check available disk space
df -h /

# 5. Check available RAM
free -h

# 6. Check if SigNoz ports are free
sudo ss -ltnp | egrep ':(3301|4317|4318|8080)\b' || echo "All ports free"

Everything working? Move on to Installation →

Read in Sequence​