Recommended Free Tools
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
If you run self-hosted SigNoz, plan to move its ClickHouse store to 25.12.5 before a future signoz-otel-collector release requires it—but do not treat that as a requirement for every collector version in use today. Back up ClickHouse data first: its on-disk format can change in place on first startup, and downgrades are not guaranteed.
For new deployments and ongoing management, SigNoz now documents Foundry, including when the deployment uses Docker Compose. The main operational pitfalls are upgrading in the right order, matching your OTLP protocol to the endpoint, and checking network reachability when telemetry goes missing.
| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
Up and Running with ClickHouse: Learn and Explore ClickHouse, It's Robust Table Engines for... | $19.95 | Buy on Amazon |
What changed for SigNoz deployments in 2026?
SigNoz’s self-hosted upgrade guide, last updated June 30, 2026, recommends upgrading the ClickHouse backing store to 25.12.5 ahead of a future signoz-otel-collector release that will require it. The guide describes this as a forward-looking compatibility change likely to arrive with a routine SigNoz update. It does not say that every collector release already requires ClickHouse 25.12.5.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsThe same guide associates the ClickHouse 25.12.5 default with the SigNoz v0.131.0 Helm chart. Check the version and image pins in your own deployment rather than assuming every installation inherits that default.
Foundry is the documented management route
SigNoz describes the older install script and repository-bundled deploy/ Compose and Swarm files as deprecated starting with v0.130.0. Foundry is now the documented route for installing and managing SigNoz, including deployments that run on Docker Compose. That distinction matters: Compose can still be the deployment platform even though the old bundled setup is deprecated.
Check the platform prerequisites
- Docker: The Docker Standalone guide lists Docker Engine 20.10 or later, or Docker Desktop on macOS or Linux; Compose v2; and at least 4 GB of memory allocated to Docker. It lists ports 8080, 4317, and 4318, plus 8000 if enabling MCP.
- Linux with systemd: The systemd guide recommends Foundry to create and manage units for SigNoz, ClickHouse, ClickHouse Keeper, PostgreSQL, the SigNoz OTel Collector, and the database migrator. It lists inbound ports 8080, 4317, and 4318. Its 4 GB minimum is for a small test installation, not a production sizing recommendation.
- Windows: The Docker guide recommends WSL 2 with Docker Engine inside WSL rather than Docker Desktop’s virtualization layer. It reports ClickHouse Keeper restart loops with segmentation faults (exit code 139) in that environment; this is a documented platform caveat, not a guarantee that every Windows setup will fail.
How do I upgrade SigNoz to ClickHouse 25.12.5?
Choose the procedure that matches your deployment, and make a restorable data backup before starting. SigNoz warns that ClickHouse may update its on-disk format in place at first startup and that rolling back to an older version is not guaranteed.
1. Back up the ClickHouse data
Snapshot the storage that contains ClickHouse data before changing versions. The upgrade guide identifies Kubernetes PersistentVolumes, the Docker volume, or /var/lib/clickhouse for a binary installation as backup targets. Confirm that you can restore the snapshot using your platform’s normal recovery process.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →2. Update a Foundry deployment
- Update
foundryctlusing the Foundry update method for your installation. - If
casting.yamlpins image versions, change the telemetry store image to ClickHouse25.12.5. If your deployment uses Keeper and pins its image separately, set that to25.12.5as well. Explicit image pins override Foundry defaults. - To update and apply the existing configuration, run
foundryctl cast -f casting.yaml. - Alternatively, render the deployment files with
foundryctl forge -f casting.yaml, then apply those files using the deployment command for your platform.
3. Update a Helm deployment
The SigNoz v0.131.0 chart sets ClickHouse 25.12.5 according to the upgrade guide. To pin that chart release, use --version 0.131.0 in your Helm upgrade command. If you are using a different chart release, or need to control the database version directly, explicitly override the ClickHouse tag in your Helm values. Check your chart values and release configuration before applying them; the exact command and values depend on how your existing release was installed.
4. Verify the migration and data flow
- Check workload health in your deployment platform.
- Run
SELECT version();against ClickHouse and confirm the running version. - Confirm that the
signoz-telemetrystore-migratorjob completed. - In SigNoz, open Meter Explorer and check that logs, traces, and metrics are arriving.
- Confirm the SigNoz version in Settings.
Why does the telemetrystore migrator say “Unknown setting ‘object_serialization_version’”?
The documented error is:
Code: 115. DB::Exception: Unknown setting 'object_serialization_version'. (UNKNOWN_SETTING)SigNoz attributes this to a version mismatch: migration settings object_serialization_version and object_shared_data_serialization_version are available only in ClickHouse 25.12.5. The new collector may be running while signoz-telemetrystore-migrator fails during its sync step if ClickHouse has not yet been upgraded. Upgrade ClickHouse to 25.12.5; the guide says the migrator should complete on its next run.
Which port and protocol should applications use?
Self-hosted SigNoz accepts OTLP/gRPC on port 4317 and OTLP/HTTP on port 4318 by default. Choose the protocol your SDK or collector supports, and use a host address reachable from the sender’s network—not necessarily the address you use in a browser.
| Protocol | When it fits | Default endpoint |
|---|---|---|
| OTLP/gRPC | SigNoz describes it as a good fit for server-side telemetry, with performance and backpressure benefits. | http://<signoz-host>:4317 |
| OTLP/HTTP | SigNoz describes it as simpler to configure and debug; use it for browser telemetry when gRPC is unsupported. | http://<signoz-host>:4318 |
These are the documented defaults; SDK support and reachable addresses vary by deployment. For HTTP, SDKs using the signal-agnostic OTEL_EXPORTER_OTLP_ENDPOINT variable append the signal path—/v1/traces, /v1/metrics, or /v1/logs—automatically. Do not append a signal path to that base endpoint unless your SDK’s configuration expects it.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallExample SDK endpoints
For gRPC without TLS, the documented configuration shape is:
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=http://<signoz-host>:4317Some SDKs also require insecure: true for a plaintext gRPC connection. For HTTP/protobuf:
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://<signoz-host>:4318Forwarding from a separate collector
A collector can export with otlp to <signoz-host>:4317, using tls.insecure: true for a plaintext endpoint, or use the otlphttp exporter with http://<signoz-host>:4318. For a TLS endpoint, use HTTPS and configure the client to trust the certificate; do not leave insecure exporter settings enabled for that connection.
Why are traces, logs, or metrics missing from SigNoz?
Work through the connection from sender to collector before changing instrumentation. A port can be open while the protocol, hostname, or path is still wrong.
- Match protocol and port: Use 4317 for OTLP/gRPC or 4318 for OTLP/HTTP, and make sure the exporter protocol agrees with that port.
- Use a reachable hostname: Check the application’s network namespace. A Docker container or Kubernetes pod may need a service name or network address rather than a host-only or localhost address.
- Check HTTP signal paths: With the signal-agnostic HTTP endpoint variable, verify that the SDK appends the correct
/v1/traces,/v1/metrics, or/v1/logspath. - Read exporter and collector logs: Look for connection refusals, DNS failures, timeouts, rejected requests, or export errors.
- Test network reachability: Check DNS resolution, firewall rules, routing, and whether the destination port is reachable from the application or collector itself.
- Validate TLS settings: For TLS, use HTTPS and check certificate trust. For a plaintext endpoint, configure the exporter accordingly; do not mix plaintext settings with a TLS listener.
- Review transient-failure handling: Collector
retry_on_failureandsending_queuecan reduce data loss during temporary outages. Choose queue and retry limits to suit event volume and available resources rather than copying arbitrary production values.
How should self-hosted OTLP endpoints be secured?
Self-hosted SigNoz does not use ingestion keys by default. For production endpoints, SigNoz’s ingestion guidance recommends TLS and enforcing authentication at a reverse proxy or Kubernetes ingress. That places access control at the exposed edge instead of relying on an ingestion key the self-hosted setup does not provide.
SDKs and collectors sending to a TLS-protected endpoint must use HTTPS and trust its certificate. Keep internal routing and endpoint exposure limited to the networks that need to send telemetry.
How can telemetry delivery be made more resilient?
Configure collector retry_on_failure and sending_queue to handle temporary downstream failures. Their appropriate limits depend on event volume and resource capacity, so the ingestion guidance does not prescribe universal production values. SDK batch export can also be tuned through the signal-specific variable families: OTEL_BSP_* for traces, OTEL_METRIC_EXPORT_* for metrics, and OTEL_BLRP_* for logs.
Quick Recap
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.
