# SigNoz Observability Platform

> SigNoz for metrics, traces, and logs.

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

## Overview

SigNoz is an open-source observability platform that provides Application Performance Monitoring (APM) capabilities through a unified interface for metrics, traces, and logs. Built as an alternative to proprietary solutions like DataDog and New Relic, SigNoz leverages OpenTelemetry standards for data collection and ClickHouse as its storage backend, offering both cost-effectiveness and data sovereignty for organizations requiring comprehensive application monitoring. This stack combines SigNoz's query service and frontend with ClickHouse's columnar database engine and an OpenTelemetry collector, creating a complete observability solution that can handle high-volume telemetry data with real-time query capabilities. The integration provides automatic correlation between traces, metrics, and logs, enabling developers to quickly identify performance bottlenecks and troubleshoot issues across distributed systems. Organizations seeking vendor-independent observability tooling will find this combination particularly valuable, as it eliminates per-seat licensing costs while maintaining enterprise-grade monitoring capabilities through ClickHouse's analytical processing power and SigNoz's intuitive dashboards.

## Features

- OpenTelemetry-native data collection supporting OTLP over gRPC (4317) and HTTP (4318) protocols
- ClickHouse columnar storage enabling sub-second query performance on billions of telemetry data points
- Distributed tracing with automatic service topology mapping and dependency visualization
- Custom metrics dashboards with PromQL-compatible query language support
- Log aggregation with structured search and correlation to traces and metrics
- Application performance monitoring with SLA tracking and alerting capabilities
- Service-level indicators (SLIs) and service-level objectives (SLOs) management
- Exception tracking with stack trace analysis and error rate monitoring

## Use cases

- Microservices monitoring for teams migrating from monolithic architectures requiring distributed tracing
- Cost-conscious startups seeking DataDog or New Relic alternatives without per-seat pricing models
- Enterprise environments with data residency requirements needing self-hosted observability solutions
- DevOps teams implementing OpenTelemetry instrumentation across polyglot application stacks
- SRE organizations establishing observability practices with custom SLI/SLO definitions
- Development teams requiring correlation between application logs, metrics, and traces in a single interface
- Organizations with high-volume telemetry data needing sub-second query performance on historical data

## Prerequisites

- Minimum 8GB RAM allocation with 16GB+ recommended for production ClickHouse workloads
- Available ports 3301 (SigNoz UI), 4317 (OTLP gRPC), and 4318 (OTLP HTTP) on the host system
- Understanding of OpenTelemetry instrumentation libraries for your application programming languages
- Basic knowledge of PromQL query syntax for creating custom metrics dashboards
- Familiarity with distributed tracing concepts including spans, traces, and sampling strategies
- Docker host with sufficient disk space for time-series data retention based on ingestion volume

## docker-compose.yml

```yaml
services:
  clickhouse:
    image: clickhouse/clickhouse-server:latest
    container_name: signoz-clickhouse
    restart: unless-stopped
    volumes:
      - clickhouse_data:/var/lib/clickhouse
    ulimits:
      nofile:
        soft: 262144
        hard: 262144

  query-service:
    image: signoz/query-service:latest
    container_name: signoz-query
    restart: unless-stopped
    environment:
      - ClickHouseUrl=tcp://clickhouse:9000
    depends_on:
      - clickhouse

  frontend:
    image: signoz/frontend:latest
    container_name: signoz-frontend
    restart: unless-stopped
    ports:
      - "${SIGNOZ_PORT:-3301}:3301"
    depends_on:
      - query-service

  otel-collector:
    image: signoz/signoz-otel-collector:latest
    container_name: signoz-otel
    restart: unless-stopped
    ports:
      - "${OTLP_GRPC:-4317}:4317"
      - "${OTLP_HTTP:-4318}:4318"
    depends_on:
      - clickhouse

volumes:
  clickhouse_data:
```

## .env

```bash
# SigNoz
SIGNOZ_PORT=3301
OTLP_GRPC=4317
OTLP_HTTP=4318
```

## Usage notes

- SigNoz UI at http://localhost:3301
- Send traces to port 4317/4318
- Configure OpenTelemetry SDKs
- ClickHouse for fast queries

## Troubleshooting

- ClickHouse 'Memory limit exceeded' errors: Increase Docker memory allocation or configure ClickHouse max_memory_usage settings
- OpenTelemetry collector connection refused on 4317/4318: Verify OTLP_GRPC and OTLP_HTTP environment variables match application endpoint configuration
- SigNoz frontend shows 'Query service unavailable': Check ClickHouseUrl environment variable and ensure ClickHouse container is healthy on port 9000
- Missing traces in SigNoz UI: Verify OpenTelemetry SDK initialization includes proper OTLP exporter endpoint configuration
- High ClickHouse disk usage: Configure data retention policies through SigNoz settings or implement ClickHouse TTL on telemetry tables
- Slow query performance in dashboards: Optimize ClickHouse table partitioning by timestamp and consider increasing clickhouse_data volume IOPS

