docker.recipes

SigNoz APM Platform

advanced

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

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.

Key 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

Common Use Cases

  • 1Microservices monitoring for e-commerce platforms tracking user journeys across services
  • 2Database query optimization using trace analysis to identify slow SQL operations
  • 3API performance monitoring for mobile app backends with high transaction volumes
  • 4Cost reduction migration from Datadog or New Relic for growing engineering teams
  • 5Compliance-focused monitoring where telemetry data must remain on-premises
  • 6Multi-tenant SaaS debugging where customer-specific performance issues need isolation
  • 7DevOps 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  clickhouse: 
3    image: clickhouse/clickhouse-server:23.11-alpine
4    container_name: signoz-clickhouse
5    volumes: 
6      - clickhouse_data:/var/lib/clickhouse
7    ulimits: 
8      nofile: 
9        soft: 262144
10        hard: 262144
11    healthcheck: 
12      test: ["CMD", "wget", "--spider", "-q", "localhost:8123/ping"]
13      interval: 10s
14      timeout: 5s
15      retries: 5
16    networks: 
17      - signoz-network
18
19  query-service: 
20    image: signoz/query-service:0.38.0
21    container_name: signoz-query
22    environment: 
23      - ClickHouseUrl=tcp://clickhouse:9000
24      - ALERTMANAGER_API_PREFIX=http://alertmanager:9093/api/
25      - SIGNOZ_LOCAL_DB_PATH=/var/lib/signoz/signoz.db
26      - DASHBOARDS_PATH=/root/config/dashboards
27      - STORAGE=clickhouse
28    volumes: 
29      - signoz_data:/var/lib/signoz
30    depends_on: 
31      clickhouse: 
32        condition: service_healthy
33    networks: 
34      - signoz-network
35
36  frontend: 
37    image: signoz/frontend:0.38.0
38    container_name: signoz-frontend
39    ports: 
40      - "3301:3301"
41    depends_on: 
42      - query-service
43    networks: 
44      - signoz-network
45
46  otel-collector: 
47    image: signoz/signoz-otel-collector:0.88.11
48    container_name: signoz-otel
49    command: ["--config=/etc/otel-collector-config.yaml"]
50    volumes: 
51      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml
52    ports: 
53      - "4317:4317"
54      - "4318:4318"
55    depends_on: 
56      - clickhouse
57    networks: 
58      - signoz-network
59
60  alertmanager: 
61    image: signoz/alertmanager:0.23.4
62    container_name: signoz-alertmanager
63    volumes: 
64      - alertmanager_data:/data
65    networks: 
66      - signoz-network
67
68volumes: 
69  clickhouse_data: 
70  signoz_data: 
71  alertmanager_data: 
72
73networks: 
74  signoz-network: 
75    driver: bridge

.env Template

.env
1# SigNoz APM
2SIGNOZ_VERSION=0.38.0

Usage Notes

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

Individual Services(5 services)

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

clickhouse
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
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
frontend:
  image: signoz/frontend:0.38.0
  container_name: signoz-frontend
  ports:
    - "3301:3301"
  depends_on:
    - query-service
  networks:
    - signoz-network
otel-collector
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
alertmanager:
  image: signoz/alertmanager:0.23.4
  container_name: signoz-alertmanager
  volumes:
    - alertmanager_data:/data
  networks:
    - signoz-network

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  clickhouse:
5    image: clickhouse/clickhouse-server:23.11-alpine
6    container_name: signoz-clickhouse
7    volumes:
8      - clickhouse_data:/var/lib/clickhouse
9    ulimits:
10      nofile:
11        soft: 262144
12        hard: 262144
13    healthcheck:
14      test: ["CMD", "wget", "--spider", "-q", "localhost:8123/ping"]
15      interval: 10s
16      timeout: 5s
17      retries: 5
18    networks:
19      - signoz-network
20
21  query-service:
22    image: signoz/query-service:0.38.0
23    container_name: signoz-query
24    environment:
25      - ClickHouseUrl=tcp://clickhouse:9000
26      - ALERTMANAGER_API_PREFIX=http://alertmanager:9093/api/
27      - SIGNOZ_LOCAL_DB_PATH=/var/lib/signoz/signoz.db
28      - DASHBOARDS_PATH=/root/config/dashboards
29      - STORAGE=clickhouse
30    volumes:
31      - signoz_data:/var/lib/signoz
32    depends_on:
33      clickhouse:
34        condition: service_healthy
35    networks:
36      - signoz-network
37
38  frontend:
39    image: signoz/frontend:0.38.0
40    container_name: signoz-frontend
41    ports:
42      - "3301:3301"
43    depends_on:
44      - query-service
45    networks:
46      - signoz-network
47
48  otel-collector:
49    image: signoz/signoz-otel-collector:0.88.11
50    container_name: signoz-otel
51    command: ["--config=/etc/otel-collector-config.yaml"]
52    volumes:
53      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml
54    ports:
55      - "4317:4317"
56      - "4318:4318"
57    depends_on:
58      - clickhouse
59    networks:
60      - signoz-network
61
62  alertmanager:
63    image: signoz/alertmanager:0.23.4
64    container_name: signoz-alertmanager
65    volumes:
66      - alertmanager_data:/data
67    networks:
68      - signoz-network
69
70volumes:
71  clickhouse_data:
72  signoz_data:
73  alertmanager_data:
74
75networks:
76  signoz-network:
77    driver: bridge
78EOF
79
80# 2. Create the .env file
81cat > .env << 'EOF'
82# SigNoz APM
83SIGNOZ_VERSION=0.38.0
84EOF
85
86# 3. Start the services
87docker compose up -d
88
89# 4. View logs
90docker compose logs -f

One-Liner

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

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

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

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

signozclickhousequery-serviceotel-collector

Tags

#signoz#apm#tracing#metrics#datadog-alternative#opentelemetry

Category

Monitoring & Observability

Related Recipes

Ad Space