eliferjunior SigNoz — Open-Source Observability Platform
Overview
SigNoz, the open-source observability platform that provides traces, metrics, and logs in a single UI. Built natively on OpenTelemetry, SigNoz is a self-hosted alternative to Datadog and New Relic. Helps developers set up distributed tracing, application performance monitoring, log management, and custom dashboards.
Instructions
Deployment
# Docker Compose (quickstart)
git clone -b main https://github.com/SigNoz/signoz.git
cd signoz/deploy
docker compose -f docker/clickhouse-setup/docker-compose.yaml up -d
# SigNoz UI at http://localhost:3301
# OTel Collector at localhost:4317 (gRPC) / localhost:4318 (HTTP)
Instrument a Node.js Application
// tracing.ts — OpenTelemetry auto-instrumentation for SigNoz
// Import this file BEFORE any other imports in your app entry point.
import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
import { Resource } from "@opentelemetry/resources";
import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
const sdk = new NodeSDK({
resource: new Resource({
[ATTR_SERVICE_NAME]: "api-gateway",
[ATTR_SERVICE_VERSION]: "1.4.2",
"deployment.environment": process.env.NODE_ENV ?? "development",
}),
traceExporter: new OTLPTraceExporter({
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? "http://localhost:4318/v1/traces",
}),
metricReader: new PeriodicExportingMetricReader({
exporter: new OTLPMetricExporter({
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? "http://localhost:4318/v1/metrics",
}),
exportIntervalMillis: 30000, // Export metrics every 30s
}),
instrumentations: [
getNodeAutoInstrumentations({
// Auto-instruments: HTTP, Express, pg, mysql, redis, MongoDB, gRPC
"@opentelemetry/instrumentation-fs": { enabled: false }, // Too noisy
}),
],
});
sdk.start();
// Graceful shutdown
process.on("SIGTERM", () => sdk.shutdown());
Custom Spans and Attributes
// src/services/order-service.ts — Add business context to traces
import { trace, SpanStatusCode, context } from "@opentelemetry/api";
const tracer = trace.getTracer("order-service");
async function processOrder(orderId: string, userId: string) {
// Create a span for the entire order processing
return tracer.startActiveSpan("process-order", async (span) => {
// Add business attributes — visible in SigNoz trace details
span.setAttribute("order.id", orderId);
span.setAttribute("user.id", userId);
try {
// Child span for payment
const paymentResult = await tracer.startActiveSpan("charge-payment", async (paymentSpan) => {
paymentSpan.setAttribute("payment.method", "stripe");
const result = await stripe.charges.create({ amount: order.total, currency: "usd" });
paymentSpan.setAttribute("payment.charge_id", result.id);
paymentSpan.end();
return result;
});
// Child span for inventory
await tracer.startActiveSpan("update-inventory", async (inventorySpan) => {
inventorySpan.setAttribute("items.count", order.items.length);
await inventoryService.reserve(order.items);
inventorySpan.end();
});
// Child span for notification
await tracer.startActiveSpan("send-confirmation", async (notifSpan) => {
await emailService.sendOrderConfirmation(userId, orderId);
notifSpan.end();
});
span.setAttribute("order.status", "completed");
span.setStatus({ code: SpanStatusCode.OK });
} catch (error) {
span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
span.recordException(error);
throw error;
} finally {
span.end();
}
});
}
Custom Metrics
// src/metrics/business-metrics.ts — Track business KPIs in SigNoz
import { metrics } from "@opentelemetry/api";
const meter = metrics.getMeter("business-metrics");
// Counter — total orders processed
const ordersProcessed = meter.createCounter("orders.processed", {
description: "Total number of orders processed",
unit: "orders",
});
// Histogram — order value distribution
const orderValue = meter.createHistogram("orders.value", {
description: "Order value in cents",
unit: "cents",
});
// Up/down counter — active users
const activeUsers = meter.createUpDownCounter("users.active", {
description: "Currently active users",
});
// Usage
function onOrderCompleted(order: Order) {
ordersProcessed.add(1, {
"order.plan": order.plan,
"order.region": order.region,
});
orderValue.record(order.totalCents, {
"order.plan": order.plan,
});
}
Structured Logging
// src/lib/logger.ts — Logs that correlate with traces in SigNoz
import pino from "pino";
import { context, trace } from "@opentelemetry/api";
const logger = pino({
mixin() {
// Inject trace context into every log line
// SigNoz correlates logs with traces using these fields
const span = trace.getSpan(context.active());
if (span) {
const spanContext = span.spanContext();
return {
trace_id: spanContext.traceId,
span_id: spanContext.spanId,
trace_flags: `0${spanContext.traceFlags.toString(16)}`,
};
}
return {};
},
transport: {
target: "pino-opentelemetry-transport",
options: {
resourceAttributes: { "service.name": "api-gateway" },
logRecordProcessorOptions: [{
exporterOptions: {
protocol: "http",
httpExporterPath: "/v1/logs",
hostname: "localhost",
port: 4318,
},
}],
},
},
});
export default logger;
Alerts
# SigNoz supports alerting on any metric or trace-based condition.
# Configure via the SigNoz UI under Settings → Alerts
# Example alert rules:
# 1. P99 latency > 2s on /api/checkout endpoint
# 2. Error rate > 5% on any service in the last 5 minutes
# 3. Orders processed = 0 for 10 minutes (business metric)
# 4. CPU usage > 80% for 5 minutes
# Notification channels: Slack, PagerDuty, webhook, email, MS Teams, Opsgenie
Installation
# Self-hosted (Docker Compose)
git clone https://github.com/SigNoz/signoz.git
cd signoz/deploy && docker compose up -d
# Helm (Kubernetes)
helm repo add signoz https://charts.signoz.io
helm install signoz signoz/signoz -n observability --create-namespace
# SigNoz Cloud (managed)
# https://signoz.io/teams/
# Client instrumentation
npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node
npm install @opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http
Examples
Example 1: Setting up Signoz for a microservices project
User request:
I have a Node.js API and a React frontend running in Docker. Set up Signoz for monitoring/deployment.
The agent creates the necessary configuration files based on patterns like # Docker Compose (quickstart), sets up the integration with the existing Docker setup, configures appropriate defaults for a Node.js + React stack, and provides verification commands to confirm everything is working.
Example 2: Troubleshooting instrument a node.js application issues
User request:
Signoz is showing errors in our instrument a node.js application. Here are the logs: [error output]
The agent analyzes the error output, identifies the root cause by cross-referencing with common Signoz issues, applies the fix (updating configuration, adjusting resource limits, or correcting syntax), and verifies the resolution with appropriate health checks.
Guidelines
- OpenTelemetry native — SigNoz uses OTel as the standard; instrument with OTel SDKs and switch between SigNoz/Datadog/Jaeger without code changes
- Auto-instrumentation first — Start with auto-instrumentation packages; add custom spans only for business-critical paths
- Correlate logs, traces, metrics — Inject trace_id into logs; SigNoz links them together in the UI for root cause analysis
- Business metrics — Track revenue, orders, signups as OTel metrics; monitor them alongside infrastructure metrics
- Tail-based sampling — For high-traffic services, configure tail-based sampling in the OTel Collector to keep errors and slow traces
- ClickHouse storage — SigNoz uses ClickHouse for storage; tune retention policies based on your data volume
- Dashboard per service — Create a SigNoz dashboard for each service with RED metrics (Rate, Errors, Duration)
- Self-host for cost — SigNoz on your infrastructure costs 5-10x less than Datadog/New Relic for the same data volume