Description
Background
We identified several challenges with our current architecture that involves separate microservices (query-service
, frontend
, and alertmanager
). These separate components made starting SigNoz unnecessarily complex and created barriers for our community. We've received multiple requests for running SigNoz as a single binary across various Linux distributions, but the fragmented architecture made this extremely difficult to implement.
Some components, like the frontend (which was essentially an nginx image serving static files), were unnecessarily separated and served no concrete purpose as independent services.
After careful consideration and extensive testing, we've decided to consolidate these components into a single binary called SigNoz. This consolidation:
- Enables us to publish a single, cohesive binary
- Reduces the number of components needed for a minimal SigNoz setup
- Provides a clean, consolidated baseline architecture
- Creates a foundation for future, more purposeful component separation (see Future Scope)
Changes
- Architecture Consolidation: The previously separate components (
query-service
,frontend
, andalertmanager
) have been combined into a single binary called SigNoz. This consolidation introduces several key changes:-
Port Consolidation: The frontend UI is now served by the same HTTP server that handles API requests, available on port
8080
(previously on port3301
). This affects:- Ingress configurations
- Reverse proxy setups
- Network policies
- Any custom access configurations
-
Component Renaming: All deployment resources have been standardized to use the name
signoz
instead of component-specific names:- Docker containers previously named
signoz-query-service
,signoz-frontend
, andsignoz-alertmanager
are now unified assignoz
- In Kubernetes deployments, this requires migrating data from previous StatefulSet persistent volumes to new ones
- Configuration files and environment variables referencing specific components must be updated
- Docker containers previously named
-
These changes require careful migration planning, especially for production environments with custom configurations or persistent data. A comprehensive documentation is available at signoz.io.
- Deprecated Docker Registries: The following Docker registries will no longer receive updates:
Existing images will remain available, but no new versions will be published to these registries.
-
New Primary Registry: The consolidated application is now available at
docker.io/signoz/signoz
. We recommend using this registry for all new installations, as it provides a seamless upgrade path to enterprise features if needed in the future. -
Open Source Registry: The community/OSS version is now available at
docker.io/signoz/signoz-community
. This replaces the previous approach where OSS builds were available atdocker.io/signoz/query-service
with the tag<version>-oss
.
Future Scope
This consolidation lays the groundwork for SigNoz's evolution toward a highly available architecture. The unified binary contains multiple services including (and not limited to) the rule evaluation engine (ruler), alertmanager, opamp websocket server, and HTTP server. Our approach offers significant flexibility for scaling:
Single Binary, Multiple Deployment Options
The consolidated SigNoz binary will remain our standard distribution format, but it's designed to support two distinct deployment patterns:
-
Unified Deployment: Run the entire SigNoz stack as a single process (ideal for small to medium deployments)
-
Service-Specific Deployment: Run individual components separately for high availability and scalability requirements
As your observability needs grow, you can transition from the unified deployment to running specific services independently. For example:
# Run only the alertmanager service
signoz --config config.yaml --services alertmanager
# Run only the ruler service
signoz --config config.yaml --services ruler
This approach enables sophisticated scaling strategies where high-traffic components can be horizontally scaled independently while maintaining a consistent codebase and configuration model. The consolidated binary gives both our community users and enterprise customers a clear, flexible path to scale their SigNoz deployments according to their specific observability requirements.
Migration Guide
Related PRs
- feat: migration guide for v0.76 signoz-web#1238
- docs: update 0.76.0 docs signoz-web#1239
- docs(single-binary): update docs for single binary signoz-web#1232
- Add single binary blog signoz-web#1233
- feat: new signoz and deprecation of frontend, alertmanager charts#631
- feat: signoz package and deprecation of frontend, alertmanager #7301
- feat(signoz): add docs for binary installation signoz-web#1241
- ci: add goreleaser and remove cgo signoz-otel-collector#558