# SigNoz

> Open-source APM and observability platform with traces, metrics, and logs.

- Category: Monitoring & Observability
- Difficulty: intermediate
- Components: signoz, clickhouse, otel-collector
- Tags: signoz, apm, tracing, observability, opentelemetry
- Source: https://docker.recipes/monitoring/signoz

## Overview

SigNoz is a comprehensive open-source Application Performance Monitoring (APM) and observability platform that provides distributed tracing, metrics collection, and log aggregation in a single unified interface. Built as a modern alternative to commercial solutions like Datadog and New Relic, SigNoz leverages OpenTelemetry standards for data collection and ClickHouse's columnar database for high-performance analytics on observability data. The platform emerged from the need for cost-effective, self-hosted observability solutions that don't compromise on performance or features.

This deployment combines SigNoz's frontend dashboard with ClickHouse as the analytical backend and OpenTelemetry Collector for telemetry data ingestion. ClickHouse's columnar storage excels at handling the high-volume, time-series nature of observability data, enabling fast queries across millions of traces and metrics. The OpenTelemetry Collector acts as the central pipeline, receiving telemetry data via OTLP protocols and processing it before storage, while SigNoz's frontend provides intuitive visualization and analysis capabilities.

This stack is ideal for engineering teams transitioning from expensive commercial APM solutions, DevOps teams implementing observability-driven development practices, and organizations requiring complete control over their monitoring data. The combination offers enterprise-grade observability features while maintaining data sovereignty and predictable costs, making it particularly valuable for companies handling sensitive data or operating under strict compliance requirements.

## 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%

## Use cases

- Migrating from expensive commercial APM solutions like Datadog or New Relic while maintaining feature parity
- Implementing observability for microservices architectures requiring distributed tracing capabilities
- Debugging performance issues in complex distributed systems with correlated logs and traces
- Monitoring high-traffic applications where commercial APM pricing becomes prohibitively expensive
- Compliance-sensitive environments requiring on-premises observability data storage and processing
- Development teams practicing observability-driven development with real-time performance feedback
- Organizations 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

```yaml
services:
  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

volumes:
  clickhouse_data:

networks:
  signoz-network:
    driver: bridge
```

## .env

```bash
# SigNoz configuration
```

## Usage notes

- Docs: https://signoz.io/docs/
- Dashboard at http://localhost:3301 - traces, metrics, logs in one place
- OTLP gRPC on 4317, HTTP on 4318 - instrument apps with OpenTelemetry SDKs
- Create signoz/otel-config.yaml before starting
- ClickHouse backend for high-performance analytics
- Open-source Datadog/New Relic alternative

## Troubleshooting

- SigNoz dashboard shows 'No data' error: Verify OpenTelemetry Collector configuration file exists and applications are properly instrumented with OTLP exporters
- ClickHouse container fails with 'Memory limit exceeded' error: Increase Docker memory allocation to minimum 4GB or add ClickHouse memory configuration limits
- OpenTelemetry Collector connection refused on port 4317/4318: Check if ports are already in use and ensure collector container started successfully with proper configuration
- SigNoz frontend shows connection errors to ClickHouse: Verify ClickHouse container is healthy and network connectivity exists between signoz and clickhouse containers
- High memory usage in ClickHouse container: Configure data retention policies and TTL settings to automatically remove old observability data
- Missing traces despite application instrumentation: Verify OTLP endpoint configuration in applications points to correct collector ports and protocols match

