How to Use SigNoz: The Beginner's Guide (Install, the OTel Endpoint, First Trace, Dashboards, and the Alert Lesson)

CodexFuse Team · 2026-10-31T23:29:22.557Z · 17 min read min read

How to Use SigNoz: The Beginner's Guide (Install, the OTel Endpoint, First Trace, Dashboards, and the Alert Lesson)

Learning how to use SigNoz is the step that turns "our metrics live in three dashboards and our logs live nowhere" into "one open-source platform answers every what-happened question." SigNoz is an open-source observability platform built natively on OpenTelemetry — it collects metrics, traces, and logs through the same open standard, stores them in ClickHouse, and shows them in a single dashboard. You run it either as SigNoz Cloud, a fully managed service with a 30-day free trial of all features, or self-hosted on your own server with Foundry, the current installer. This signoz tutorial — the signoz for beginners guide the field is missing — walks the complete beginner arc: the cloud-versus-self-host decision, the Foundry install, the OTel endpoint rule, your first instrumented app, your first trace, your first logs, your first dashboard, and the alert lesson. Everything below was verified against the live SigNoz documentation, the SigNoz GitHub repository, and current release data, because the install method changed in 2026 and half the tutorials on the internet still teach the old one.

You will do this in order: decide between Cloud and self-host with a clear cost picture, install the stack with Foundry on Docker (the Docker beginner guide covers the container basics if you need them), point an instrumented app at the OTLP endpoint, find your first trace, read the dashboards, send logs through the same endpoint, build a custom dashboard, and set up your first alert. If you have never touched observability tooling, the OpenTelemetry beginner guide explains the instrumentation half of this stack — SigNoz is the backend half, and this guide starts where that one ends.

What is SigNoz, exactly?

SigNoz is an open-source application performance monitoring and observability platform that speaks OpenTelemetry natively — it ingests metrics, traces, and logs from any OpenTelemetry-instrumented application and gives you dashboards, a trace explorer, log search, service maps, and alerts in one UI. The project lives at github.com/SigNoz/signoz, carries roughly 32,500 stars, dates back to January 2021, and is under active development (the latest release, v0.148.1, landed on October 29, 2026). The community code is MIT-licensed; the enterprise-only directories in the repository carry their own commercial license. Unlike Datadog or New Relic, there are no per-seat fees on the self-hosted path and no proprietary agent — your SDKs emit standard OTLP, so you can walk away from SigNoz and point them at any other backend tomorrow. That is the open source observability platform promise in one sentence: the tool earns your continued use instead of buying it with lock-in.

How does SigNoz work with OpenTelemetry?

SigNoz is the backend that your OpenTelemetry SDKs and Collectors send data to — it does not replace them. Your application gets instrumented with an OpenTelemetry SDK (the code that creates spans and metrics), the SDK exports telemetry to an OTLP endpoint, and SigNoz listens on that endpoint, stores the data in ClickHouse, and renders it. The OTLP endpoint rule is the one sentence to memorize: gRPC on port 4317, HTTP on port 4318 — so a self-hosted app points OTEL_EXPORTER_OTLP_ENDPOINT at http://localhost:4318 (or host:4317 for gRPC), while a Cloud app points at ingest.<region>.signoz.cloud:443 with an ingestion key in the signoz-ingestion-key header. This is what the signoz opentelemetry pairing really is: OpenTelemetry handles every instrumenting decision in your code, and SigNoz handles everything after the export. Because SigNoz only understands open formats, the same setup also accepts Jaeger- and Zipkin-format data — nothing is locked to a vendor agent.

Should you use SigNoz Cloud or self-host it?

Pick SigNoz Cloud if you want telemetry flowing in minutes with zero server responsibility; self-host if data control or long-term cost matters more than convenience. SigNoz Cloud is the fully managed edition — no storage to manage, no upgrades to run, SOC2 Type 2 compliance, SSO, and granular access control out of the box — with a 30-day free trial of all features for new accounts. Self-hosting is free software-wise (MIT community code) but it is a real infrastructure commitment: ClickHouse, Postgres, and an OTEL Collector all run as containers and need at least 4GB of RAM for Docker. The default retention reflects that trade-off too — 7 days for logs and traces, 30 days for metrics — so long-term history is cheaper on your own disks than on someone else's meter.

For a first run, Cloud is the honest recommendation: it removes the entire install half of this guide and lets you learn the product before you commit to operating it. Everything after the install section applies identically either way — the dashboards, the alerts, and the mistakes to avoid do not care where the server lives.

What do you need before you install SigNoz?

You need a machine with Docker installed, at least 4GB of RAM for the containers, and three open ports: 8080 for the SigNoz UI, 4317 and 4318 for OTLP ingestion. The signoz docker route is the beginner path — one compose-style stack, no Kubernetes required. On a home network, a spare machine or a Linux VM works; for anything you will keep, a VPS is the right home — the what is VPS hosting guide explains the sizing, but the short version is that ClickHouse wants real memory, not the cheapest 1GB box. Windows users should run everything inside a WSL 2 distribution with Docker Engine installed natively — SigNoz's own docs warn that ClickHouse Keeper can crash in a restart loop under Docker Desktop's virtualization layer. Mac users should give Docker Desktop at least 4GB in its settings before starting.

How do you install SigNoz with Foundry?

Foundry is the current, supported way to install self-hosted SigNoz — a small installer that validates your environment, generates the Docker Compose files, and starts the stack. This signoz install takes minutes on a machine that meets the requirements above. Follow these steps in order:

1. Install foundryctl. Run the installer script:

   curl -fsSL https://signoz.io/foundry.sh | bash

   (On Windows PowerShell or air-gapped machines, follow the manual steps in the Foundry getting-started guide instead.)
2. Create casting.yaml. The casting file declares what to install — a Docker Compose flavor for local Docker:

   apiVersion: v1alpha1
   kind: Installation
   metadata:
     name: signoz
   spec:
     deployment:
       flavor: compose
       mode: docker

3. Deploy.

   foundryctl cast -f casting.yaml

   This chains three stages: gauge validates your prerequisites, forge renders the Compose files into pours/, and cast starts the containers. If you prefer to inspect first, run

   foundryctl gauge -f casting.yaml
   foundryctl forge -f casting.yaml
   cd pours/deployment && docker compose up -d

4. Verify the containers.

   docker ps

   You should see ClickHouse, Postgres, the clickhouse-keeper, the signoz-otel-collector on ports 4317–4318, and the signoz server itself — all healthy.
5. Open the UI. Point your browser at

   http://localhost:8080/

   (or http://<your-server-IP>:8080/ on a VPS).
6. Check the health endpoint.

   curl http://localhost:8080/api/v1/health

   A working install answers

   {"status":"ok"}

   .
7. Create your account. The first visit walks you through creating the admin user — email, name, organization, password. This is local-only; nobody else sees it.

Everything after this point — instruments, dashboards, alerts — is identical whether you arrived here via Foundry or via Cloud.

What happened to the old install.sh?

The legacy install.sh script and the Docker Compose files bundled under deploy/ in the SigNoz repository are deprecated as of SigNoz v0.130.0 and are no longer maintained or distributed. If a tutorial tells you to git clone the signoz repo and run ./install.sh, it is teaching a dead path — and if it tells you the UI lives on port 3301, it is even older. The UI moved to port 8080 in the current architecture, and Foundry is what the official docs now install. This is the freshness lesson for every observability tutorial: an install guide from 2024 can be structurally wrong today even when every command still "works" against an old release.

How do you send your first trace to SigNoz?

You instrument an app with an OpenTelemetry SDK and point the OTLP exporter at SigNoz's ingestion endpoint — SigNoz then discovers the service automatically. The fastest path is the OpenTelemetry Demo app, a ready-made microservices demo that emits traces, metrics, and logs: follow SigNoz's "Send Sample Telemetry" quickstart, which points the demo's collector at your endpoint. The two environment variables that matter:

# Self-hosted (HTTP flavor — the simplest first choice)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

# SigNoz Cloud (gRPC flavor with the ingestion key)
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.us.signoz.cloud:443
OTEL_EXPORTER_OTLP_HEADERS=signoz-ingestion-key=<your-ingestion-key>

Two gotchas that eat every beginner's first hour: on the gRPC port (4317), the endpoint must NOT carry an http:// scheme — write host:4317, not http://host:4317 — and on Cloud the region in the endpoint must match the region of your account, or the key will be rejected. Set the service name with OTEL_SERVICE_NAME so the dashboard labels your app something human. Give it a minute of traffic, then open the Services tab — your service should appear with RED metrics: request rate, error percentage, and latency percentiles, computed automatically from your spans.

How do you read your first trace in SigNoz?

Open the signoz traces explorer, click any trace, and read the waterfall: each row is a span (one unit of work), nested under its parent, with its duration as a bar. Click a span to see its attributes — the key-value details the SDK attached, like http.method, db.statement, or the error message on a failed span. The beginner's reading order is: find the slowest span in the waterfall (that is your bottleneck), check its attributes for the exact query or call, then use "View related logs" to jump from that span into the logs emitted at the same moment. That trace-to-log jump is the moment SigNoz stops being three tools and becomes one — and it only works because everything arrived through the same OTel pipeline.

What can you see on a SigNoz dashboard?

The Services dashboard shows every detected service with its RED metrics out of the box: rate (requests per second), errors (error percentage), and duration (p50/p95/p99 latency) — no configuration needed. Click a service to open its overview: an operations list (each endpoint with its own RED numbers), a dependency graph of which services call which, and tabs for Traces, Logs, Metrics, and Exceptions. Exceptions deserve special attention: SigNoz groups your app's exceptions with full stack traces, so the "what is crashing in production" question gets answered without touching a log file. Dashboards refresh live by default; change the time range in the top bar to zoom from the last 15 minutes out to the last week.

How do logs work in SigNoz?

Logs travel through the same OTLP endpoint as traces and metrics — there is no separate logging stack to install. Enable your SDK's log instrumentation (for example, the OpenTelemetry logging bridge in your language's SDK) and point it at the same OTEL_EXPORTER_OTLP_ENDPOINT; SigNoz stores the logs in ClickHouse and shows them in the Logs tab, where the field list on the side lets you filter by severity, service, or any attribute. Because logs share the trace context, every log line from an instrumented request carries its trace ID — the "correlated logs" idea that used to require a separate ELK stack arrives as a default. This is the architecture lesson worth remembering: one endpoint, one storage engine (the ClickHouse beginner guide explains the database doing the heavy lifting), three signal types.

How do you build your first custom dashboard?

Go to Dashboards, create one, and add a widget — each widget is a query over one signal type, built with the query builder or raw ClickHouse-flavored SQL. A good first dashboard has four widgets: (1) request rate per service over time, (2) p95 latency per endpoint, (3) error percentage per service, and (4) a log stream filtered to severity ERROR. Use the query builder's GROUP BY to split each widget by service.name so one panel covers all services. Save the dashboard and set the time range to "Last 1 hour" — dashboards are saved with their queries but not their time range, so every viewer picks their own window. Signoz dashboards refresh live, and if you find yourself rebuilding the same panels for every project, you have outgrown custom dashboards and want alerts instead.

How do you set up your first alert?

Go to Alerts, create an alert rule, and anchor it to a symptom your users would feel — the classic first alert is "error percentage above 5% for 5 minutes on the checkout service." Pick the metric query (error rate by service), set the threshold and the evaluation window, then attach a notification channel: signoz alerts support the usual suspects like Slack, PagerDuty, email, and webhooks. Two rules keep alerts useful: alert on symptoms (error rate, latency), not causes (CPU at 80% pages nobody should wake up for), and give every alert a runbook link in its description — the person paged at 3 AM should land on "here is what to check" instead of a blank query page. Start with two or three alerts; a wall of fifty alerts is just a second inbox, and it will be ignored like one.

SigNoz vs Grafana: which one should you pick?

Pick SigNoz when you want an opinionated, OTel-native observability backend that works the moment data arrives; pick Grafana when you need a visualization layer over many different backends you already run. They are not the same job. SigNoz bundles storage (ClickHouse), ingestion (OTel Collector), and the UI into one coherent product with built-in RED metrics, exception grouping, and trace-to-log correlation. Grafana is a dashboarding frontend that queries whatever you point it at — Prometheus, Loki, Tempo, Elasticsearch — and leaves the storage, ingestion, and correlation wiring to you.

The Prometheus beginner guide covers the metrics-backend half of the Grafana stack if you are weighing the two architectures. Neither choice is wrong — but do not run both for the same signals. Two observability stacks is how you get zero people looking at either.

7 mistakes every SigNoz beginner makes

Sources

Every fact in this guide was verified at write time (November 1, 2026). Release and project data: GitHub SigNoz/signoz releases API — v0.148.1 released October 29, 2026, approximately 32,500 stars, repository created January 2021; the LICENSE file confirms MIT for community code with enterprise directories under a separate license. Install method: signoz.io/docs/install/docker — the legacy install.sh and bundled deploy/ Compose files are deprecated as of v0.130.0, Foundry (foundry.sh → foundryctl cast) is the supported path, UI on port 8080, OTLP on 4317/4318, minimum 4GB RAM for Docker, default retention 7 days for logs and traces and 30 days for metrics. Cloud: signoz.io/docs/cloud — fully managed, SOC2 Type 2, SSO, granular access control, 30-day free trial of all features for new accounts. Endpoint patterns: the SigNoz Kubernetes docs confirm the OTEL_EXPORTER_OTLP_ENDPOINT conventions; a SigNoz-authored EKS monitoring tutorial confirms the Cloud ingest pattern (ingest.<region>.signoz.cloud:443 with the signoz-ingestion-key header). Port history: community tutorials from 2021–2023 document the old localhost:3301 UI port, confirming the port move that current guides must reflect.

Frequently Asked Questions

Is SigNoz really free?

The self-hosted community edition is MIT-licensed and free to run — your only cost is the server underneath it. SigNoz Cloud is a paid managed service with a 30-day free trial of all features. Enterprise-only features in the ee/ directory of the repository carry a separate commercial license, so check the pricing page if you need SSO-at-scale features beyond the community build.

How much RAM does SigNoz need?

At least 4GB of RAM for the Docker containers, per the official docs — ClickHouse is the hungry one. A 2GB VPS will technically start the stack and then spend its life swapping. For a first experiment, a 4GB machine is the floor; production sizing depends on your telemetry volume, and the retention settings are the main knob.

Does SigNoz replace Prometheus and Grafana?

It replaces the job they do together, not the tools themselves. SigNoz is a complete observability backend — ingestion, ClickHouse storage, dashboards, alerts — built around OpenTelemetry. A Prometheus + Grafana stack stays the better choice if you already run it or need Grafana's multi-backend flexibility. If you are starting from zero with OTel-instrumented apps, SigNoz gets you to "everything in one place" faster.

Can SigNoz monitor logs without a separate logging stack?

Yes — that is one of its main selling points. Logs arrive through the same OTLP endpoint as traces and metrics (4317/4318), land in ClickHouse, and are searchable in the Logs tab, correlated with traces by trace ID. No Elasticsearch, no Loki, no second pipeline.

Why is my service not showing up in SigNoz?

Work the checklist in order: is the stack healthy (curl localhost:8080/api/v1/health → {"status":"ok"}), is your app pointing at the right port (4318 for HTTP, 4317 for gRPC — not 8080), does the gRPC endpoint have no http:// scheme, is the Cloud ingestion key in the signoz-ingestion-key header, and did you set OTEL_SERVICE_NAME? Nine times out of ten it is the port or the scheme.