How to Deploy SigNoz in 2026: Upgrade ClickHouse and Fix OTel Issues

For self-hosted SigNoz, the ClickHouse version is the first thing to check: SigNoz’s upgrade guide, last updated June 30, 2026, recommends moving the backing store to ClickHouse 25.12.5 before a future signoz-otel-collector release requires it. That is forward-looking guidance, not evidence that every collector version already requires 25.12.5. Back up ClickHouse data before upgrading: its on-disk format can change in place on first start, and a downgrade is not guaranteed.

What changed in SigNoz deployment?

SigNoz’s documented installation and management route is now Foundry. The Docker installation guide says the legacy install script and repository-bundled deploy/ Compose and Swarm files were deprecated as of SigNoz v0.130.0. Foundry can manage a deployment that uses Docker Compose; Compose itself is not the deprecated part.

#	Preview	Product	Price
1		Up and Running with ClickHouse: Learn and Explore ClickHouse, It's Robust Table Engines for...	$19.95	Buy on Amazon

As an Amazon Associate I earn from qualifying purchases.

The upgrade guide for SigNoz v0.131.0 describes a ClickHouse 25.12.5 upgrade ahead of a future collector requirement. It says this change may arrive as part of a routine SigNoz update, but recommends handling the ClickHouse change in a controlled way. If you have pinned image versions in casting.yaml, those pins take precedence over defaults.

How do I upgrade SigNoz to ClickHouse 25.12.5?

Choose the procedure that matches your deployment. First take a backup of the ClickHouse data, then change the version and verify the deployment after it starts.

#1 Best Overall

Up and Running with ClickHouse: Learn and Explore ClickHouse, It's Robust Table Engines for Analytical Tasks, ClickHouse SQL, Integration with ... the ClickHouse Server (English Edition)

$19.95

Buy on Amazon

Before changing ClickHouse

ClickHouse can update its on-disk format in place on first start. SigNoz warns that rollback to an older version is not guaranteed. Before proceeding, snapshot the relevant Kubernetes PersistentVolumes, Docker volume, or—on a binary installation—/var/lib/clickhouse. Keep the snapshot until you have confirmed the upgraded deployment is healthy and telemetry is flowing.

Foundry-managed deployment

1. Update foundryctl using the method appropriate to your installation.
2. Inspect casting.yaml for explicitly pinned images. Set the telemetry store image to ClickHouse 25.12.5; if your deployment uses Keeper and pins its image separately, set that to 25.12.5 as well.
3. Reapply the existing configuration with foundryctl cast -f casting.yaml. Alternatively, render the files with foundryctl forge -f casting.yaml and apply them with the deployment command for your platform.
4. Check workload health, wait for the signoz-telemetrystore-migrator job to complete, and confirm the SigNoz version in Settings.
5. Run SELECT version(); against ClickHouse and confirm that logs, traces, and metrics appear in Meter Explorer.

Helm-managed deployment

The SigNoz v0.131.0 chart sets ClickHouse to 25.12.5, according to the upgrade guide. You can pin that chart release with --version 0.131.0, or explicitly override the ClickHouse image tag in your chart values. Review your existing values before applying an update so you do not unintentionally discard deployment-specific configuration. Afterward, verify the migrator, ClickHouse version, SigNoz version, and incoming telemetry as you would for a Foundry deployment.

SigNoz’s upgrade instructions describe the jump as significant and advise reviewing the guide and backing up to protect existing data. The advice applies to the documented upgrade, not as a blanket claim that all deployments have identical settings or upgrade steps.

Why does the SigNoz telemetrystore migrator say Unknown setting 'object_serialization_version'?

The upgrade guide documents this error when a newer collector is used before ClickHouse has reached 25.12.5. The collector pod may remain running even while the signoz-telemetrystore-migrator fails during its sync step. The reported error is:

Code: 115. DB::Exception: Unknown setting 'object_serialization_version'. (UNKNOWN_SETTING)

SigNoz attributes the failure to migration settings—object_serialization_version and object_shared_data_serialization_version—that are available only in ClickHouse 25.12.5. Upgrade ClickHouse to the documented version; the migrator should complete on its next run. Confirm that the job succeeds rather than treating a running collector pod as proof that migration completed.

Which ports does self-hosted SigNoz use for OTLP?

The self-hosted ingestion guide, last updated August 25, 2026, lists port 4317 for OTLP/gRPC and 4318 for OTLP/HTTP. SigNoz’s self-hosted/community setup does not use ingestion keys by default.

Those are documented defaults, not a guarantee that the ports are exposed or reachable in every deployment. SDK support and the address reachable from the application’s network must also match your setup.

How do I configure an application or collector to send telemetry?

For application SDKs, select a protocol and give the exporter the corresponding reachable host and port. A common configuration shape in SigNoz’s ingestion guide is:

# OTLP/gRPC
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=http://<signoz-host>:4317

# OTLP/HTTP with protobuf
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://<signoz-host>:4318

For gRPC without TLS, the guide uses an http:// endpoint and notes that some SDKs also need insecure: true. For HTTP/protobuf, SDKs using the signal-agnostic OTEL_EXPORTER_OTLP_ENDPOINT append the signal-specific path—/v1/traces, /v1/metrics, or /v1/logs—automatically. Check your SDK’s behavior if you set a signal-specific endpoint or construct the request URL yourself.

You can also send telemetry through a separately deployed OpenTelemetry Collector that forwards to SigNoz. The guide’s plain-endpoint examples use an otlp exporter targeting <signoz-host>:4317 with tls.insecure: true, or an otlphttp exporter targeting http://<signoz-host>:4318. Do not use an insecure TLS setting for an endpoint that expects verified TLS.

Production access and TLS

Because self-hosted ingestion has no ingestion key by default, SigNoz advises enforcing authentication at a reverse proxy or Kubernetes ingress. For production endpoints, use TLS: expose HTTPS through that proxy or ingress and ensure that applications and collectors trust the certificate. Restrict network access to the telemetry endpoint as appropriate for your deployment.

Handling temporary export failures

SigNoz recommends configuring collector retry_on_failure and sending_queue to reduce data loss during transient failures. It also identifies SDK batch-export variables for tuning: OTEL_BSP_* for traces, OTEL_METRIC_EXPORT_* for metrics, and OTEL_BLRP_* for logs. Queue and batch values depend on event volume and available resources; the documentation does not establish one production setting that fits every workload.

Why are my OpenTelemetry traces, logs, or metrics not showing up in SigNoz?

Work through the connection from the application outward. A correct port alone is not enough: the protocol, address, network route, and HTTP signal path all have to agree.

1. Check the port from the sender’s network. Test reachability to port 4317 for gRPC or 4318 for HTTP from the application or forwarding collector—not just from the host running SigNoz.
2. Match protocol and endpoint. Confirm that an exporter configured for gRPC is using the gRPC endpoint and that HTTP/protobuf is using the HTTP endpoint. A reachable port with the wrong protocol can still fail.
3. Use the address visible to the sender. An address that works on the host may not resolve inside a Docker network or from a Kubernetes pod. Use the host, service name, or other address reachable from the sender’s network namespace.
4. Check HTTP signal paths. When using the signal-agnostic HTTP endpoint variable, confirm that the SDK appends the appropriate /v1/traces, /v1/metrics, or /v1/logs path.
5. Read exporter and collector logs. Look for connection, export, or retry errors, then check DNS resolution, firewall rules, and routing between the sender and SigNoz.
6. Verify TLS settings. If the endpoint uses TLS, send to HTTPS and check certificate trust. Do not leave insecure exporter settings enabled for a TLS endpoint.
7. Investigate transient failures. Review collector retry and sending-queue behavior if telemetry stops during temporary network or receiver interruptions.

Which installation environment does the documentation support?

Docker Compose and standalone Docker

Use Foundry to manage a SigNoz deployment even when it runs on Docker Compose; the older bundled deployment files and install script are the deprecated route. The Docker standalone guide lists Docker Engine 20.10 or later, or Docker Desktop on macOS/Linux, Compose v2, and at least 4 GB allocated to Docker. That memory figure is an installation prerequisite in the guide, not a production-sizing recommendation. It lists ports 8080, 4317, and 4318; port 8000 is additionally needed if enabling MCP.

Linux systemd

The Linux systemd guide recommends Foundry to create and manage units for SigNoz, ClickHouse, ClickHouse Keeper, PostgreSQL, the SigNoz OpenTelemetry Collector, and the database migrator. It lists inbound ports 8080 for the UI and 4317/4318 for OTLP. Its at-least-4-GB figure applies to a small test installation; the guide directs production operators to separate resource-planning material.

Windows through WSL 2

The Docker guide directs Windows users to WSL 2 with Docker Engine inside WSL rather than Docker Desktop’s virtualization layer. It reports that ClickHouse Keeper has entered a restart loop with segmentation faults (exit code 139) in that environment. Treat this as a documented platform caveat, not a guarantee that every Windows or Docker configuration will behave the same way.

Quick Recap

Bestseller No. 1

Up and Running with ClickHouse: Learn and Explore ClickHouse, It's Robust Table Engines for Analytical Tasks, ClickHouse SQL, Integration with ... the ClickHouse Server (English Edition)

$19.95

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.