SigNoz

Key Features

• Distributed tracing with flame graphs and trace topology visualization using OpenTelemetry standards
• Real-time metrics dashboard with custom aggregations powered by ClickHouse's analytical engine
• Unified logs, traces, and metrics correlation in a single interface for faster debugging
• OTLP protocol support on both gRPC (4317) and HTTP (4318) for universal application instrumentation
• High-performance query engine capable of analyzing billions of telemetry events in milliseconds
• Built-in alerting system with custom metric thresholds and notification integrations
• Service topology mapping showing dependencies and performance bottlenecks across microservices
• Cost-effective data retention with ClickHouse's compression reducing storage requirements by up to 90%

Common Use Cases

• 1Migrating from expensive commercial APM solutions like Datadog or New Relic while maintaining feature parity
• 2Implementing observability for microservices architectures requiring distributed tracing capabilities
• 3Debugging performance issues in complex distributed systems with correlated logs and traces
• 4Monitoring high-traffic applications where commercial APM pricing becomes prohibitively expensive
• 5Compliance-sensitive environments requiring on-premises observability data storage and processing
• 6Development teams practicing observability-driven development with real-time performance feedback
• 7Organizations needing custom retention policies and advanced analytics on observability data

Prerequisites

• Docker Engine 20.10+ and Docker Compose V2 for container orchestration support
• Minimum 4GB RAM available (2GB for ClickHouse, 1GB for SigNoz, 1GB for system overhead)
• Available ports 3301 (SigNoz UI), 4317 (OTLP gRPC), and 4318 (OTLP HTTP) for service access
• OpenTelemetry Collector configuration file at ./signoz/otel-config.yaml with appropriate receivers and processors
• Basic understanding of OpenTelemetry instrumentation for connecting applications to the collector
• At least 20GB free disk space for initial ClickHouse data storage and log retention

docker-compose.yml

1services: 
2  clickhouse: 
3    image: clickhouse/clickhouse-server:latest
4    container_name: signoz-clickhouse
5    restart: unless-stopped
6    volumes: 
7      - clickhouse_data:/var/lib/clickhouse
8    networks: 
9      - signoz-network
10
11  otel-collector: 
12    image: signoz/signoz-otel-collector:latest
13    container_name: otel-collector
14    restart: unless-stopped
15    command: --config=/etc/otel-collector-config.yaml
16    volumes: 
17      - ./signoz/otel-config.yaml:/etc/otel-collector-config.yaml:ro
18    ports: 
19      - "4317:4317"
20      - "4318:4318"
21    depends_on: 
22      - clickhouse
23    networks: 
24      - signoz-network
25
26  signoz: 
27    image: signoz/frontend:latest
28    container_name: signoz
29    restart: unless-stopped
30    ports: 
31      - "3301:3301"
32    depends_on: 
33      - clickhouse
34    networks: 
35      - signoz-network
36
37volumes: 
38  clickhouse_data: 
39
40networks: 
41  signoz-network: 
42    driver: bridge

.env Template

1# SigNoz configuration

Usage Notes

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

clickhouse:
  image: clickhouse/clickhouse-server:latest
  container_name: signoz-clickhouse
  restart: unless-stopped
  volumes:
    - clickhouse_data:/var/lib/clickhouse
  networks:
    - signoz-network

otel-collector:
  image: signoz/signoz-otel-collector:latest
  container_name: otel-collector
  restart: unless-stopped
  command: "--config=/etc/otel-collector-config.yaml"
  volumes:
    - ./signoz/otel-config.yaml:/etc/otel-collector-config.yaml:ro
  ports:
    - "4317:4317"
    - "4318:4318"
  depends_on:
    - clickhouse
  networks:
    - signoz-network

signoz:
  image: signoz/frontend:latest
  container_name: signoz
  restart: unless-stopped
  ports:
    - "3301:3301"
  depends_on:
    - clickhouse
  networks:
    - signoz-network

Quick Start

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  clickhouse:
5    image: clickhouse/clickhouse-server:latest
6    container_name: signoz-clickhouse
7    restart: unless-stopped
8    volumes:
9      - clickhouse_data:/var/lib/clickhouse
10    networks:
11      - signoz-network
12
13  otel-collector:
14    image: signoz/signoz-otel-collector:latest
15    container_name: otel-collector
16    restart: unless-stopped
17    command: --config=/etc/otel-collector-config.yaml
18    volumes:
19      - ./signoz/otel-config.yaml:/etc/otel-collector-config.yaml:ro
20    ports:
21      - "4317:4317"
22      - "4318:4318"
23    depends_on:
24      - clickhouse
25    networks:
26      - signoz-network
27
28  signoz:
29    image: signoz/frontend:latest
30    container_name: signoz
31    restart: unless-stopped
32    ports:
33      - "3301:3301"
34    depends_on:
35      - clickhouse
36    networks:
37      - signoz-network
38
39volumes:
40  clickhouse_data:
41
42networks:
43  signoz-network:
44    driver: bridge
45EOF
46
47# 2. Create the .env file
48cat > .env << 'EOF'
49# SigNoz configuration
50EOF
51
52# 3. Start the services
53docker compose up -d
54
55# 4. View logs
56docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

1curl -fsSL https://docker.recipes/api/recipes/signoz/run | bash

Troubleshooting