# SigNoz APM Platform

> SigNoz open-source APM with distributed tracing, metrics, and logs.

- Category: Monitoring & Observability
- Difficulty: advanced
- Components: signoz, clickhouse, query-service, otel-collector
- Tags: signoz, apm, tracing, metrics, datadog-alternative, opentelemetry
- Source: https://docker.recipes/monitoring/signoz-apm

## Overview

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

This stack combines SigNoz's query service and frontend with ClickHouse's columnar database engine and OpenTelemetry Collector for data ingestion. The query service acts as the API layer, processing requests from the React-based frontend while executing complex analytical queries against ClickHouse. The OpenTelemetry Collector receives telemetry data from instrumented applications via OTLP protocols, processes and enriches the data, then forwards it to ClickHouse for storage. Alertmanager handles notification routing and alert deduplication based on rules defined in the SigNoz interface.

This configuration suits engineering teams transitioning from expensive SaaS APM solutions, startups requiring comprehensive observability without vendor lock-in, and organizations with data sovereignty requirements. The combination delivers enterprise-grade APM capabilities while maintaining full control over telemetry data and avoiding per-seat or data volume pricing models that can become prohibitively expensive at scale.

## Features

- Distributed tracing with flame graphs showing request flows across microservices
- Custom metrics dashboards with PromQL-compatible query language
- Log aggregation with correlation to traces and metrics using trace IDs
- ClickHouse-powered sub-second query performance on billions of telemetry events
- OpenTelemetry native instrumentation supporting 15+ programming languages
- Service topology mapping with dependency graphs and error rate visualization
- Alert rules with Slack, PagerDuty, and webhook integrations via Alertmanager
- Exception tracking with stack trace analysis and occurrence patterns

## Use cases

- Microservices monitoring for e-commerce platforms tracking user journeys across services
- Database query optimization using trace analysis to identify slow SQL operations
- API performance monitoring for mobile app backends with high transaction volumes
- Cost reduction migration from Datadog or New Relic for growing engineering teams
- Compliance-focused monitoring where telemetry data must remain on-premises
- Multi-tenant SaaS debugging where customer-specific performance issues need isolation
- DevOps pipeline monitoring to track deployment impact on application performance

## Prerequisites

- Docker host with minimum 8GB RAM (ClickHouse requires 2GB+ for reasonable performance)
- Available ports 3301 (SigNoz UI), 4317 (OTLP gRPC), and 4318 (OTLP HTTP)
- OpenTelemetry Collector configuration file (otel-collector-config.yaml) with processors and exporters
- Application instrumentation with OpenTelemetry SDKs pointing to collector endpoints
- Understanding of distributed tracing concepts and service mesh architectures
- Basic ClickHouse query knowledge for custom metric exploration and debugging

## docker-compose.yml

```yaml
services:
  clickhouse:
    image: clickhouse/clickhouse-server:23.11-alpine
    container_name: signoz-clickhouse
    volumes:
      - clickhouse_data:/var/lib/clickhouse
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "localhost:8123/ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - signoz-network

  query-service:
    image: signoz/query-service:0.38.0
    container_name: signoz-query
    environment:
      - ClickHouseUrl=tcp://clickhouse:9000
      - ALERTMANAGER_API_PREFIX=http://alertmanager:9093/api/
      - SIGNOZ_LOCAL_DB_PATH=/var/lib/signoz/signoz.db
      - DASHBOARDS_PATH=/root/config/dashboards
      - STORAGE=clickhouse
    volumes:
      - signoz_data:/var/lib/signoz
    depends_on:
      clickhouse:
        condition: service_healthy
    networks:
      - signoz-network

  frontend:
    image: signoz/frontend:0.38.0
    container_name: signoz-frontend
    ports:
      - "3301:3301"
    depends_on:
      - query-service
    networks:
      - signoz-network

  otel-collector:
    image: signoz/signoz-otel-collector:0.88.11
    container_name: signoz-otel
    command: ["--config=/etc/otel-collector-config.yaml"]
    volumes:
      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml
    ports:
      - "4317:4317"
      - "4318:4318"
    depends_on:
      - clickhouse
    networks:
      - signoz-network

  alertmanager:
    image: signoz/alertmanager:0.23.4
    container_name: signoz-alertmanager
    volumes:
      - alertmanager_data:/data
    networks:
      - signoz-network

volumes:
  clickhouse_data:
  signoz_data:
  alertmanager_data:

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

## .env

```bash
# SigNoz APM
SIGNOZ_VERSION=0.38.0
```

## Usage notes

- UI at http://localhost:3301
- OTLP gRPC at localhost:4317
- OTLP HTTP at localhost:4318
- Create otel-collector-config.yaml
- Use official SigNoz install script for production

## Troubleshooting

- ClickHouse startup fails with 'Cannot allocate memory': Increase Docker memory limits to 4GB+ and set proper ulimits for file descriptors
- Query service cannot connect to ClickHouse: Verify ClickHouseUrl environment variable uses correct hostname and port 9000 (not HTTP port 8123)
- No traces appearing in SigNoz UI: Check OpenTelemetry Collector logs for export errors and verify OTLP endpoint configuration in application instrumentation
- Frontend shows 'Query Service Unavailable': Ensure query-service container started after ClickHouse health check passes and check network connectivity
- High memory usage in ClickHouse: Configure proper TTL policies for trace data retention and enable compression in table definitions
- Alertmanager notifications not sending: Verify webhook URLs are accessible from container and check Alertmanager configuration reload status

