feat(factory): add service state tracking, AwaitHealthy, depends_on, and /healthz (#10671)

* feat(factory): add service state tracking, AwaitHealthy, depends_on, and /healthz endpoint

Add explicit lifecycle state tracking to factory.Registry services
(starting/running/failed) modeled after Guava's ServiceManager. Services
can declare dependencies via NewNamedService(..., dependsOn) which are
validated for unknown refs and cycles at registry creation. AwaitHealthy
blocks until all services reach running state. A /healthz endpoint is
wired through signozapiserver returning 200/503 with per-service state.

* feat(apiserver): move health endpoints to /api/v2/ and register readyz, livez

* refactor(factory): use gonum for cycle detection, return error on cycles, fix test assertions

Replace custom DFS cycle detection with gonum's topo.Sort + TarjanSCC.
Dependency cycles now return an error from NewRegistry instead of being
silently dropped. Use assert for final test assertions and require only
for intermediate setup errors.

* chore: go mod tidy

* refactor(factory): decouple Handler from Registry, wire through Handlers struct

Move Handler implementation to a private handler struct with NewHandler
constructor instead of methods on *Registry. Route handler through the
existing Handlers struct as RegistryHandler. Rename healthz.go to
registry.go in signozapiserver. Fix handler_test.go for new param.

* feat(factory): add ServiceWithHealthy interface, add Healthy to authz, user depends on authz

Add ServiceWithHealthy interface embedding Service + Healthy. NamedService
now delegates Healthy() to the underlying service, eliminating unwrapService.
AuthZ interface requires Healthy(), implemented in both pkg and ee providers.
User service declares dependency on authz via dependsOn.

* test(integration): use /api/v2/healthz for readiness check, log 503 response body

* fix(factory): replace fmt.Errorf with errors.Newf in tests to satisfy linter

* feat: generate openapi spec

* fix(integration): log errors at error level in healthz readiness check

* test(integration): log and assert healthz response in test_setup

* feat(user): implement ServiceWithHealthy for user service

User service signals healthy after successful root user reconciliation
or immediately when disabled. User Service interface now embeds
factory.ServiceWithHealthy.

* fix(factory): reflect service names as strings

* fix(apiserver): document health 503 responses

* feat: generate openapi spec

docs/api/openapi.yml

@@ -417,6 +417,18 @@ components:
         message:
           type: string
       type: object
+    FactoryResponse:
+      properties:
+        healthy:
+          type: boolean
+        services:
+          additionalProperties:
+            items:
+              type: string
+            type: array
+          nullable: true
+          type: object
+      type: object
     FeaturetypesGettableFeature:
       properties:
         defaultVariant:
@@ -5984,6 +5996,70 @@ paths:
       summary: Search ingestion keys for workspace
       tags:
       - gateway
+  /api/v2/healthz:
+    get:
+      operationId: Healthz
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                properties:
+                  data:
+                    $ref: '#/components/schemas/FactoryResponse'
+                  status:
+                    type: string
+                required:
+                - status
+                - data
+                type: object
+          description: OK
+        "503":
+          content:
+            application/json:
+              schema:
+                properties:
+                  data:
+                    $ref: '#/components/schemas/FactoryResponse'
+                  status:
+                    type: string
+                required:
+                - status
+                - data
+                type: object
+          description: Service Unavailable
+      summary: Health check
+      tags:
+      - health
+  /api/v2/livez:
+    get:
+      deprecated: false
+      description: ""
+      operationId: Livez
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                properties:
+                  data:
+                    $ref: '#/components/schemas/FactoryResponse'
+                  status:
+                    type: string
+                required:
+                - status
+                - data
+                type: object
+          description: OK
+        "500":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Internal Server Error
+      summary: Liveness check
+      tags:
+      - health
   /api/v2/metrics:
     get:
       deprecated: false
@@ -6660,6 +6736,41 @@ paths:
       summary: Update my organization
       tags:
       - orgs
+  /api/v2/readyz:
+    get:
+      operationId: Readyz
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                properties:
+                  data:
+                    $ref: '#/components/schemas/FactoryResponse'
+                  status:
+                    type: string
+                required:
+                - status
+                - data
+                type: object
+          description: OK
+        "503":
+          content:
+            application/json:
+              schema:
+                properties:
+                  data:
+                    $ref: '#/components/schemas/FactoryResponse'
+                  status:
+                    type: string
+                required:
+                - status
+                - data
+                type: object
+          description: Service Unavailable
+      summary: Readiness check
+      tags:
+      - health
   /api/v2/sessions:
     delete:
       deprecated: false

docs/contributing/onboarding.md

@@ -273,6 +273,7 @@ Options can be simple (direct link) or nested (with another question):
 - Place logo files in `public/Logos/`
 - Use SVG format
 - Reference as `"/Logos/your-logo.svg"`
+- **Fetching Icons**: New icons can be easily fetched from [OpenBrand](https://openbrand.sh/). Use the pattern `https://openbrand.sh/?url=<TARGET_URL>`, where `<TARGET_URL>` is the URL-encoded link to the service's website. For example, to get Render's logo, use [https://openbrand.sh/?url=https%3A%2F%2Frender.com](https://openbrand.sh/?url=https%3A%2F%2Frender.com).
 - **Optimize new SVGs**: Run any newly downloaded SVGs through an optimizer like [SVGOMG (svgo)](https://svgomg.net/) or use `npx svgo public/Logos/your-logo.svg` to minimise their size before committing.
 
 ### 4. Links

ee/authz/openfgaauthz/provider.go

@@ -57,6 +57,10 @@ func (provider *provider) Start(ctx context.Context) error {
 	return provider.openfgaServer.Start(ctx)
 }
 
+func (provider *provider) Healthy() <-chan struct{} {
+	return provider.openfgaServer.Healthy()
+}
+
 func (provider *provider) Stop(ctx context.Context) error {
 	return provider.openfgaServer.Stop(ctx)
 }

ee/authz/openfgaserver/server.go

@@ -16,7 +16,6 @@ type Server struct {
 }
 
 func NewOpenfgaServer(ctx context.Context, pkgAuthzService authz.AuthZ) (*Server, error) {
-
 	return &Server{
 		pkgAuthzService: pkgAuthzService,
 	}, nil
@@ -26,6 +25,10 @@ func (server *Server) Start(ctx context.Context) error {
 	return server.pkgAuthzService.Start(ctx)
 }
 
+func (server *Server) Healthy() <-chan struct{} {
+	return server.pkgAuthzService.Healthy()
+}
+
 func (server *Server) Stop(ctx context.Context) error {
 	return server.pkgAuthzService.Stop(ctx)
 }

frontend/public/Logos/mistral.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="#fa520f" viewBox="0 0 24 24"><title>Mistral AI</title><path d="M17.143 3.429v3.428h-3.429v3.429h-3.428V6.857H6.857V3.43H3.43v13.714H0v3.428h10.286v-3.428H6.857v-3.429h3.429v3.429h3.429v-3.429h3.428v3.429h-3.428v3.428H24v-3.428h-3.43V3.429z"/></svg>

frontend/public/Logos/openclaw.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 120 120"><defs><linearGradient id="a" x1="0%" x2="100%" y1="0%" y2="100%"><stop offset="0%" stop-color="#ff4d4d"/><stop offset="100%" stop-color="#991b1b"/></linearGradient></defs><path fill="url(#a)" d="M60 10c-30 0-45 25-45 45s15 40 30 45v10h10v-10s5 2 10 0v10h10v-10c15-5 30-25 30-45S90 10 60 10"/><path fill="url(#a)" d="M20 45C5 40 0 50 5 60s15 5 20-5c3-7 0-10-5-10"/><path fill="url(#a)" d="M100 45c15-5 20 5 15 15s-15 5-20-5c-3-7 0-10 5-10"/><path stroke="#ff4d4d" stroke-linecap="round" stroke-width="3" d="M45 15Q35 5 30 8M75 15Q85 5 90 8"/><circle cx="45" cy="35" r="6" fill="#050810"/><circle cx="75" cy="35" r="6" fill="#050810"/><circle cx="46" cy="34" r="2.5" fill="#00e5cc"/><circle cx="76" cy="34" r="2.5" fill="#00e5cc"/></svg>

frontend/public/Logos/render.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><title>Render</title><path d="M18.263.007c-3.121-.147-5.744 2.109-6.192 5.082-.018.138-.045.272-.067.405-.696 3.703-3.936 6.507-7.827 6.507a7.9 7.9 0 0 1-3.825-.979.202.202 0 0 0-.302.178V24H12v-8.999c0-1.656 1.338-3 2.987-3h2.988c3.382 0 6.103-2.817 5.97-6.244-.12-3.084-2.61-5.603-5.682-5.75"/></svg>

frontend/src/api/generated/services/health/index.ts

@@ -0,0 +1,250 @@
+/**
+ * ! Do not edit manually
+ * * The file has been auto-generated using Orval for SigNoz
+ * * regenerate with 'yarn generate:api'
+ * SigNoz
+ */
+import type {
+	InvalidateOptions,
+	QueryClient,
+	QueryFunction,
+	QueryKey,
+	UseQueryOptions,
+	UseQueryResult,
+} from 'react-query';
+import { useQuery } from 'react-query';
+
+import type { ErrorType } from '../../../generatedAPIInstance';
+import { GeneratedAPIInstance } from '../../../generatedAPIInstance';
+import type {
+	Healthz200,
+	Healthz503,
+	Livez200,
+	Readyz200,
+	Readyz503,
+	RenderErrorResponseDTO,
+} from '../sigNoz.schemas';
+
+/**
+ * @summary Health check
+ */
+export const healthz = (signal?: AbortSignal) => {
+	return GeneratedAPIInstance<Healthz200>({
+		url: `/api/v2/healthz`,
+		method: 'GET',
+		signal,
+	});
+};
+
+export const getHealthzQueryKey = () => {
+	return [`/api/v2/healthz`] as const;
+};
+
+export const getHealthzQueryOptions = <
+	TData = Awaited<ReturnType<typeof healthz>>,
+	TError = ErrorType<Healthz503>
+>(options?: {
+	query?: UseQueryOptions<Awaited<ReturnType<typeof healthz>>, TError, TData>;
+}) => {
+	const { query: queryOptions } = options ?? {};
+
+	const queryKey = queryOptions?.queryKey ?? getHealthzQueryKey();
+
+	const queryFn: QueryFunction<Awaited<ReturnType<typeof healthz>>> = ({
+		signal,
+	}) => healthz(signal);
+
+	return { queryKey, queryFn, ...queryOptions } as UseQueryOptions<
+		Awaited<ReturnType<typeof healthz>>,
+		TError,
+		TData
+	> & { queryKey: QueryKey };
+};
+
+export type HealthzQueryResult = NonNullable<
+	Awaited<ReturnType<typeof healthz>>
+>;
+export type HealthzQueryError = ErrorType<Healthz503>;
+
+/**
+ * @summary Health check
+ */
+
+export function useHealthz<
+	TData = Awaited<ReturnType<typeof healthz>>,
+	TError = ErrorType<Healthz503>
+>(options?: {
+	query?: UseQueryOptions<Awaited<ReturnType<typeof healthz>>, TError, TData>;
+}): UseQueryResult<TData, TError> & { queryKey: QueryKey } {
+	const queryOptions = getHealthzQueryOptions(options);
+
+	const query = useQuery(queryOptions) as UseQueryResult<TData, TError> & {
+		queryKey: QueryKey;
+	};
+
+	query.queryKey = queryOptions.queryKey;
+
+	return query;
+}
+
+/**
+ * @summary Health check
+ */
+export const invalidateHealthz = async (
+	queryClient: QueryClient,
+	options?: InvalidateOptions,
+): Promise<QueryClient> => {
+	await queryClient.invalidateQueries(
+		{ queryKey: getHealthzQueryKey() },
+		options,
+	);
+
+	return queryClient;
+};
+
+/**
+ * @summary Liveness check
+ */
+export const livez = (signal?: AbortSignal) => {
+	return GeneratedAPIInstance<Livez200>({
+		url: `/api/v2/livez`,
+		method: 'GET',
+		signal,
+	});
+};
+
+export const getLivezQueryKey = () => {
+	return [`/api/v2/livez`] as const;
+};
+
+export const getLivezQueryOptions = <
+	TData = Awaited<ReturnType<typeof livez>>,
+	TError = ErrorType<RenderErrorResponseDTO>
+>(options?: {
+	query?: UseQueryOptions<Awaited<ReturnType<typeof livez>>, TError, TData>;
+}) => {
+	const { query: queryOptions } = options ?? {};
+
+	const queryKey = queryOptions?.queryKey ?? getLivezQueryKey();
+
+	const queryFn: QueryFunction<Awaited<ReturnType<typeof livez>>> = ({
+		signal,
+	}) => livez(signal);
+
+	return { queryKey, queryFn, ...queryOptions } as UseQueryOptions<
+		Awaited<ReturnType<typeof livez>>,
+		TError,
+		TData
+	> & { queryKey: QueryKey };
+};
+
+export type LivezQueryResult = NonNullable<Awaited<ReturnType<typeof livez>>>;
+export type LivezQueryError = ErrorType<RenderErrorResponseDTO>;
+
+/**
+ * @summary Liveness check
+ */
+
+export function useLivez<
+	TData = Awaited<ReturnType<typeof livez>>,
+	TError = ErrorType<RenderErrorResponseDTO>
+>(options?: {
+	query?: UseQueryOptions<Awaited<ReturnType<typeof livez>>, TError, TData>;
+}): UseQueryResult<TData, TError> & { queryKey: QueryKey } {
+	const queryOptions = getLivezQueryOptions(options);
+
+	const query = useQuery(queryOptions) as UseQueryResult<TData, TError> & {
+		queryKey: QueryKey;
+	};
+
+	query.queryKey = queryOptions.queryKey;
+
+	return query;
+}
+
+/**
+ * @summary Liveness check
+ */
+export const invalidateLivez = async (
+	queryClient: QueryClient,
+	options?: InvalidateOptions,
+): Promise<QueryClient> => {
+	await queryClient.invalidateQueries({ queryKey: getLivezQueryKey() }, options);
+
+	return queryClient;
+};
+
+/**
+ * @summary Readiness check
+ */
+export const readyz = (signal?: AbortSignal) => {
+	return GeneratedAPIInstance<Readyz200>({
+		url: `/api/v2/readyz`,
+		method: 'GET',
+		signal,
+	});
+};
+
+export const getReadyzQueryKey = () => {
+	return [`/api/v2/readyz`] as const;
+};
+
+export const getReadyzQueryOptions = <
+	TData = Awaited<ReturnType<typeof readyz>>,
+	TError = ErrorType<Readyz503>
+>(options?: {
+	query?: UseQueryOptions<Awaited<ReturnType<typeof readyz>>, TError, TData>;
+}) => {
+	const { query: queryOptions } = options ?? {};
+
+	const queryKey = queryOptions?.queryKey ?? getReadyzQueryKey();
+
+	const queryFn: QueryFunction<Awaited<ReturnType<typeof readyz>>> = ({
+		signal,
+	}) => readyz(signal);
+
+	return { queryKey, queryFn, ...queryOptions } as UseQueryOptions<
+		Awaited<ReturnType<typeof readyz>>,
+		TError,
+		TData
+	> & { queryKey: QueryKey };
+};
+
+export type ReadyzQueryResult = NonNullable<Awaited<ReturnType<typeof readyz>>>;
+export type ReadyzQueryError = ErrorType<Readyz503>;
+
+/**
+ * @summary Readiness check
+ */
+
+export function useReadyz<
+	TData = Awaited<ReturnType<typeof readyz>>,
+	TError = ErrorType<Readyz503>
+>(options?: {
+	query?: UseQueryOptions<Awaited<ReturnType<typeof readyz>>, TError, TData>;
+}): UseQueryResult<TData, TError> & { queryKey: QueryKey } {
+	const queryOptions = getReadyzQueryOptions(options);
+
+	const query = useQuery(queryOptions) as UseQueryResult<TData, TError> & {
+		queryKey: QueryKey;
+	};
+
+	query.queryKey = queryOptions.queryKey;
+
+	return query;
+}
+
+/**
+ * @summary Readiness check
+ */
+export const invalidateReadyz = async (
+	queryClient: QueryClient,
+	options?: InvalidateOptions,
+): Promise<QueryClient> => {
+	await queryClient.invalidateQueries(
+		{ queryKey: getReadyzQueryKey() },
+		options,
+	);
+
+	return queryClient;
+};

frontend/src/api/generated/services/sigNoz.schemas.ts

@@ -543,6 +543,23 @@ export interface ErrorsResponseerroradditionalDTO {
 	message?: string;
 }
 
+/**
+ * @nullable
+ */
+export type FactoryResponseDTOServices = { [key: string]: string[] } | null;
+
+export interface FactoryResponseDTO {
+	/**
+	 * @type boolean
+	 */
+	healthy?: boolean;
+	/**
+	 * @type object
+	 * @nullable true
+	 */
+	services?: FactoryResponseDTOServices;
+}
+
 /**
  * @nullable
  */
@@ -3457,6 +3474,30 @@ export type SearchIngestionKeys200 = {
 	status: string;
 };
 
+export type Healthz200 = {
+	data: FactoryResponseDTO;
+	/**
+	 * @type string
+	 */
+	status: string;
+};
+
+export type Healthz503 = {
+	data: FactoryResponseDTO;
+	/**
+	 * @type string
+	 */
+	status: string;
+};
+
+export type Livez200 = {
+	data: FactoryResponseDTO;
+	/**
+	 * @type string
+	 */
+	status: string;
+};
+
 export type ListMetricsParams = {
 	/**
 	 * @type integer
@@ -3592,6 +3633,22 @@ export type GetMyOrganization200 = {
 	status: string;
 };
 
+export type Readyz200 = {
+	data: FactoryResponseDTO;
+	/**
+	 * @type string
+	 */
+	status: string;
+};
+
+export type Readyz503 = {
+	data: FactoryResponseDTO;
+	/**
+	 * @type string
+	 */
+	status: string;
+};
+
 export type GetSessionContext200 = {
 	data: AuthtypesSessionContextDTO;
 	/**

frontend/src/container/OnboardingV2Container/onboarding-configs/onboarding-config-with-links.json

@@ -6122,5 +6122,95 @@
 		],
 		"id": "huggingface-observability",
 		"link": "/docs/huggingface-observability/"
+	},
+	{
+		"dataSource": "mistral-observability",
+		"label": "Mistral AI",
+		"imgUrl": "/Logos/mistral.svg",
+		"tags": [
+			"LLM Monitoring"
+		],
+		"module": "apm",
+		"relatedSearchKeywords": [
+			"llm",
+			"llm monitoring",
+			"mistral",
+			"mistral ai",
+			"monitoring",
+			"observability",
+			"otel mistral",
+			"traces",
+			"tracing"
+		],
+		"id": "mistral-observability",
+		"link": "/docs/mistral-observability/"
+	},
+	{
+		"dataSource": "openclaw-observability",
+		"label": "OpenClaw",
+		"imgUrl": "/Logos/openclaw.svg",
+		"tags": [
+			"LLM Monitoring"
+		],
+		"module": "apm",
+		"relatedSearchKeywords": [
+			"llm",
+			"llm monitoring",
+			"monitoring",
+			"observability",
+			"openclaw",
+			"otel openclaw",
+			"traces",
+			"tracing"
+		],
+		"id": "openclaw-observability",
+		"link": "/docs/openclaw-monitoring/"
+	},
+	{
+		"dataSource": "claude-agent-monitoring",
+		"label": "Claude Agent SDK",
+		"imgUrl": "/Logos/claude-code.svg",
+		"tags": [
+			"LLM Monitoring"
+		],
+		"module": "apm",
+		"relatedSearchKeywords": [
+			"anthropic",
+			"claude",
+			"claude agent",
+			"claude agent sdk",
+			"claude sdk",
+			"llm",
+			"llm monitoring",
+			"monitoring",
+			"observability",
+			"otel claude",
+			"traces",
+			"tracing"
+		],
+		"id": "claude-agent-monitoring",
+		"link": "/docs/claude-agent-monitoring/"
+	},
+	{
+		"dataSource": "render-metrics",
+		"label": "Render",
+		"imgUrl": "/Logos/render.svg",
+		"tags": [
+			"infrastructure monitoring",
+			"metrics"
+		],
+		"module": "metrics",
+		"relatedSearchKeywords": [
+			"infrastructure",
+			"metrics",
+			"monitoring",
+			"observability",
+			"paas",
+			"render",
+			"render metrics",
+			"render monitoring"
+		],
+		"id": "render-metrics",
+		"link": "/docs/metrics-management/render-metrics/"
 	}
 ]

go.mod

@@ -81,6 +81,8 @@ require (
 	golang.org/x/oauth2 v0.34.0
 	golang.org/x/sync v0.19.0
 	golang.org/x/text v0.33.0
+	gonum.org/v1/gonum v0.17.0
+	google.golang.org/api v0.265.0
 	google.golang.org/protobuf v1.36.11
 	gopkg.in/yaml.v2 v2.4.0
 	gopkg.in/yaml.v3 v3.0.1
@@ -377,8 +379,6 @@ require (
 	golang.org/x/sys v0.40.0 // indirect
 	golang.org/x/time v0.14.0 // indirect
 	golang.org/x/tools v0.41.0 // indirect
-	gonum.org/v1/gonum v0.17.0 // indirect
-	google.golang.org/api v0.265.0
 	google.golang.org/genproto/googleapis/api v0.0.0-20260203192932-546029d2fa20 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20260128011058-8636f8732409 // indirect
 	google.golang.org/grpc v1.78.0 // indirect

pkg/apiserver/signozapiserver/provider.go

@@ -50,6 +50,7 @@ type provider struct {
 	zeusHandler            zeus.Handler
 	querierHandler         querier.Handler
 	serviceAccountHandler  serviceaccount.Handler
+	factoryHandler         factory.Handler
 }
 
 func NewFactory(
@@ -72,6 +73,7 @@ func NewFactory(
 	zeusHandler zeus.Handler,
 	querierHandler querier.Handler,
 	serviceAccountHandler serviceaccount.Handler,
+	factoryHandler factory.Handler,
 ) factory.ProviderFactory[apiserver.APIServer, apiserver.Config] {
 	return factory.NewProviderFactory(factory.MustNewName("signoz"), func(ctx context.Context, providerSettings factory.ProviderSettings, config apiserver.Config) (apiserver.APIServer, error) {
 		return newProvider(
@@ -97,6 +99,7 @@ func NewFactory(
 			zeusHandler,
 			querierHandler,
 			serviceAccountHandler,
+			factoryHandler,
 		)
 	})
 }
@@ -124,6 +127,7 @@ func newProvider(
 	zeusHandler zeus.Handler,
 	querierHandler querier.Handler,
 	serviceAccountHandler serviceaccount.Handler,
+	factoryHandler factory.Handler,
 ) (apiserver.APIServer, error) {
 	settings := factory.NewScopedProviderSettings(providerSettings, "github.com/SigNoz/signoz/pkg/apiserver/signozapiserver")
 	router := mux.NewRouter().UseEncodedPath()
@@ -149,6 +153,7 @@ func newProvider(
 		zeusHandler:            zeusHandler,
 		querierHandler:         querierHandler,
 		serviceAccountHandler:  serviceAccountHandler,
+		factoryHandler:         factoryHandler,
 	}
 
 	provider.authZ = middleware.NewAuthZ(settings.Logger(), orgGetter, authz)
@@ -233,6 +238,10 @@ func (provider *provider) AddToRouter(router *mux.Router) error {
 		return err
 	}
 
+	if err := provider.addRegistryRoutes(router); err != nil {
+		return err
+	}
+
 	return nil
 }
 

pkg/apiserver/signozapiserver/registry.go

@@ -0,0 +1,84 @@
+package signozapiserver
+
+import (
+	"net/http"
+
+	"github.com/SigNoz/signoz/pkg/factory"
+	pkghandler "github.com/SigNoz/signoz/pkg/http/handler"
+	"github.com/SigNoz/signoz/pkg/http/render"
+	"github.com/gorilla/mux"
+	openapi "github.com/swaggest/openapi-go"
+)
+
+type healthOpenAPIHandler struct {
+	handlerFunc http.HandlerFunc
+	id          string
+	summary     string
+}
+
+func newHealthOpenAPIHandler(handlerFunc http.HandlerFunc, id, summary string) pkghandler.Handler {
+	return &healthOpenAPIHandler{
+		handlerFunc: handlerFunc,
+		id:          id,
+		summary:     summary,
+	}
+}
+
+func (handler *healthOpenAPIHandler) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
+	handler.handlerFunc.ServeHTTP(rw, req)
+}
+
+func (handler *healthOpenAPIHandler) ServeOpenAPI(opCtx openapi.OperationContext) {
+	opCtx.SetID(handler.id)
+	opCtx.SetTags("health")
+	opCtx.SetSummary(handler.summary)
+
+	response := render.SuccessResponse{
+		Status: render.StatusSuccess.String(),
+		Data:   new(factory.Response),
+	}
+
+	opCtx.AddRespStructure(
+		response,
+		openapi.WithContentType("application/json"),
+		openapi.WithHTTPStatus(http.StatusOK),
+	)
+	opCtx.AddRespStructure(
+		response,
+		openapi.WithContentType("application/json"),
+		openapi.WithHTTPStatus(http.StatusServiceUnavailable),
+	)
+}
+
+func (provider *provider) addRegistryRoutes(router *mux.Router) error {
+	if err := router.Handle("/api/v2/healthz", newHealthOpenAPIHandler(
+		provider.authZ.OpenAccess(provider.factoryHandler.Healthz),
+		"Healthz",
+		"Health check",
+	)).Methods(http.MethodGet).GetError(); err != nil {
+		return err
+	}
+
+	if err := router.Handle("/api/v2/readyz", newHealthOpenAPIHandler(
+		provider.authZ.OpenAccess(provider.factoryHandler.Readyz),
+		"Readyz",
+		"Readiness check",
+	)).Methods(http.MethodGet).GetError(); err != nil {
+		return err
+	}
+
+	if err := router.Handle("/api/v2/livez", pkghandler.New(provider.authZ.OpenAccess(provider.factoryHandler.Livez),
+		pkghandler.OpenAPIDef{
+			ID:                  "Livez",
+			Tags:                []string{"health"},
+			Summary:             "Liveness check",
+			Response:            new(factory.Response),
+			ResponseContentType: "application/json",
+			SuccessStatusCode:   http.StatusOK,
+		},
+	)).Methods(http.MethodGet).GetError(); err != nil {
+		return err
+	}
+
+	return nil
+}

pkg/authz/authz.go

@@ -11,7 +11,7 @@ import (
 )
 
 type AuthZ interface {
-	factory.Service
+	factory.ServiceWithHealthy
 
 	// CheckWithTupleCreation takes upon the responsibility for generating the tuples alongside everything Check does.
 	CheckWithTupleCreation(context.Context, authtypes.Claims, valuer.UUID, authtypes.Relation, authtypes.Typeable, []authtypes.Selector, []authtypes.Selector) error

pkg/authz/openfgaauthz/provider.go

@@ -43,6 +43,10 @@ func (provider *provider) Start(ctx context.Context) error {
 	return provider.server.Start(ctx)
 }
 
+func (provider *provider) Healthy() <-chan struct{} {
+	return provider.server.Healthy()
+}
+
 func (provider *provider) Stop(ctx context.Context) error {
 	return provider.server.Stop(ctx)
 }

pkg/authz/openfgaserver/server.go

@@ -31,6 +31,7 @@ type Server struct {
 	modelID       string
 	mtx           sync.RWMutex
 	stopChan      chan struct{}
+	healthyC      chan struct{}
 }
 
 func NewOpenfgaServer(ctx context.Context, settings factory.ProviderSettings, config authz.Config, sqlstore sqlstore.SQLStore, openfgaSchema []openfgapkgtransformer.ModuleFile) (*Server, error) {
@@ -61,6 +62,7 @@ func NewOpenfgaServer(ctx context.Context, settings factory.ProviderSettings, co
 		openfgaSchema: openfgaSchema,
 		mtx:           sync.RWMutex{},
 		stopChan:      make(chan struct{}),
+		healthyC:      make(chan struct{}),
 	}, nil
 }
 
@@ -80,10 +82,16 @@ func (server *Server) Start(ctx context.Context) error {
 	server.storeID = storeID
 	server.mtx.Unlock()
 
+	close(server.healthyC)
+
 	<-server.stopChan
 	return nil
 }
 
+func (server *Server) Healthy() <-chan struct{} {
+	return server.healthyC
+}
+
 func (server *Server) Stop(ctx context.Context) error {
 	server.openfgaServer.Close()
 	close(server.stopChan)

pkg/factory/handler.go

@@ -0,0 +1,67 @@
+package factory
+
+import (
+	"net/http"
+
+	"github.com/SigNoz/signoz/pkg/http/render"
+)
+
+// Handler provides HTTP handler functions for service health checks.
+type Handler interface {
+	// Readyz reports whether services are ready.
+	Readyz(http.ResponseWriter, *http.Request)
+
+	// Livez reports whether services are alive.
+	Livez(http.ResponseWriter, *http.Request)
+
+	// Healthz reports overall service health.
+	Healthz(http.ResponseWriter, *http.Request)
+}
+
+type handler struct {
+	registry *Registry
+}
+
+func NewHandler(registry *Registry) Handler {
+	return &handler{
+		registry: registry,
+	}
+}
+
+type Response struct {
+	Healthy  bool             `json:"healthy"`
+	Services map[State][]Name `json:"services"`
+}
+
+func (handler *handler) Healthz(rw http.ResponseWriter, req *http.Request) {
+	byState := handler.registry.ServicesByState()
+	healthy := handler.registry.IsHealthy()
+
+	statusCode := http.StatusOK
+	if !healthy {
+		statusCode = http.StatusServiceUnavailable
+	}
+
+	render.Success(rw, statusCode, Response{
+		Healthy:  healthy,
+		Services: byState,
+	})
+}
+
+func (handler *handler) Readyz(rw http.ResponseWriter, req *http.Request) {
+	healthy := handler.registry.IsHealthy()
+
+	statusCode := http.StatusOK
+	if !healthy {
+		statusCode = http.StatusServiceUnavailable
+	}
+
+	render.Success(rw, statusCode, Response{
+		Healthy:  healthy,
+		Services: handler.registry.ServicesByState(),
+	})
+}
+
+func (handler *handler) Livez(rw http.ResponseWriter, req *http.Request) {
+	render.Success(rw, http.StatusOK, nil)
+}

pkg/factory/name.go

@@ -5,9 +5,11 @@ import (
 	"regexp"
 
 	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/swaggest/jsonschema-go"
 )
 
 var _ slog.LogValuer = (Name{})
+var _ jsonschema.Exposer = (Name{})
 
 var (
 	// nameRegex is a regex that matches a valid name.
@@ -27,6 +29,21 @@ func (n Name) String() string {
 	return n.name
 }
 
+// MarshalText implements encoding.TextMarshaler for JSON serialization.
+func (n Name) MarshalText() ([]byte, error) {
+	return []byte(n.name), nil
+}
+
+// MarshalJSON implements json.Marshaler so Name serializes as a JSON string.
+func (n Name) MarshalJSON() ([]byte, error) {
+	return []byte(`"` + n.name + `"`), nil
+}
+
+// JSONSchema implements jsonschema.Exposer so OpenAPI reflects Name as a string.
+func (n Name) JSONSchema() (jsonschema.Schema, error) {
+	return *new(jsonschema.Schema).WithType(jsonschema.String.Type()), nil
+}
+
 // NewName creates a new name.
 func NewName(name string) (Name, error) {
 	if !nameRegex.MatchString(name) {

pkg/factory/registry.go

@@ -8,21 +8,26 @@ import (
 	"syscall"
 
 	"github.com/SigNoz/signoz/pkg/errors"
+	"gonum.org/v1/gonum/graph/simple"
+	"gonum.org/v1/gonum/graph/topo"
 )
 
 var (
-	ErrCodeInvalidRegistry = errors.MustNewCode("invalid_registry")
+	ErrCodeInvalidRegistry  = errors.MustNewCode("invalid_registry")
+	ErrCodeDependencyFailed = errors.MustNewCode("dependency_failed")
+	ErrCodeServiceFailed    = errors.MustNewCode("service_failed")
 )
 
 type Registry struct {
-	services NamedMap[NamedService]
-	logger   *slog.Logger
-	startCh  chan error
-	stopCh   chan error
+	services       []*serviceWithState
+	servicesByName map[Name]*serviceWithState
+	logger         *slog.Logger
+	startC         chan error
+	stopC          chan error
 }
 
 // New creates a new registry of services. It needs at least one service in the input.
-func NewRegistry(logger *slog.Logger, services ...NamedService) (*Registry, error) {
+func NewRegistry(ctx context.Context, logger *slog.Logger, services ...NamedService) (*Registry, error) {
 	if logger == nil {
 		return nil, errors.Newf(errors.TypeInvalidInput, ErrCodeInvalidRegistry, "cannot build registry, logger is required")
 	}
@@ -31,59 +36,131 @@ func NewRegistry(logger *slog.Logger, services ...NamedService) (*Registry, erro
 		return nil, errors.Newf(errors.TypeInvalidInput, ErrCodeInvalidRegistry, "cannot build registry, at least one service is required")
 	}
 
-	m, err := NewNamedMap(services...)
-	if err != nil {
+	servicesWithState := make([]*serviceWithState, len(services))
+	servicesByName := make(map[Name]*serviceWithState, len(services))
+	for i, s := range services {
+		if _, ok := servicesByName[s.Name()]; ok {
+			return nil, errors.Newf(errors.TypeInvalidInput, ErrCodeInvalidRegistry, "cannot build registry, duplicate service name %q", s.Name())
+		}
+		ss := newServiceWithState(s)
+		servicesWithState[i] = ss
+		servicesByName[s.Name()] = ss
+	}
+
+	registryLogger := logger.With(slog.String("pkg", "github.com/SigNoz/signoz/pkg/factory"))
+
+	for _, ss := range servicesWithState {
+		for _, dep := range ss.service.DependsOn() {
+			if dep == ss.service.Name() {
+				registryLogger.ErrorContext(ctx, "ignoring self-dependency", slog.Any("service", ss.service.Name()))
+				continue
+			}
+
+			if _, ok := servicesByName[dep]; !ok {
+				registryLogger.ErrorContext(ctx, "ignoring unknown dependency", slog.Any("service", ss.service.Name()), slog.Any("dependency", dep))
+				continue
+			}
+
+			ss.dependsOn = append(ss.dependsOn, dep)
+		}
+	}
+
+	if err := detectCyclicDeps(servicesWithState); err != nil {
 		return nil, err
 	}
 
 	return &Registry{
-		logger:   logger.With(slog.String("pkg", "go.signoz.io/pkg/factory")),
-		services: m,
-		startCh:  make(chan error, 1),
-		stopCh:   make(chan error, len(services)),
+		logger:         registryLogger,
+		services:       servicesWithState,
+		servicesByName: servicesByName,
+		startC:         make(chan error, 1),
+		stopC:          make(chan error, len(services)),
 	}, nil
 }
 
-func (r *Registry) Start(ctx context.Context) {
-	for _, s := range r.services.GetInOrder() {
-		go func(s NamedService) {
-			r.logger.InfoContext(ctx, "starting service", slog.Any("service", s.Name()))
-			err := s.Start(ctx)
-			r.startCh <- err
-		}(s)
-	}
+func (registry *Registry) Start(ctx context.Context) {
+	for _, ss := range registry.services {
+		go func(ss *serviceWithState) {
+			// Wait for all dependencies to be healthy before starting.
+			for _, dep := range ss.dependsOn {
+				depState := registry.servicesByName[dep]
+				registry.logger.InfoContext(ctx, "service waiting for dependency", slog.Any("service", ss.service.Name()), slog.Any("dependency", dep))
+				select {
+				case <-ctx.Done():
+					ss.mu.Lock()
+					ss.state = StateFailed
+					ss.startErr = ctx.Err()
+					ss.mu.Unlock()
+					close(ss.startReturnedC)
+					registry.startC <- ctx.Err()
+					return
+				case <-depState.healthyC:
+					// Dependency is healthy, continue.
+				case <-depState.startReturnedC:
+					// Dependency failed before becoming healthy.
+					err := errors.Newf(errors.TypeInternal, ErrCodeDependencyFailed, "dependency %q of service %q failed", dep, ss.service.Name())
+					ss.mu.Lock()
+					ss.state = StateFailed
+					ss.startErr = err
+					ss.mu.Unlock()
+					close(ss.startReturnedC)
+					registry.startC <- err
+					return
+				}
+			}
 
+			registry.logger.InfoContext(ctx, "starting service", slog.Any("service", ss.service.Name()))
+
+			go func() {
+				select {
+				case <-ss.service.Healthy():
+					ss.setState(StateRunning)
+				case <-ss.startReturnedC:
+				}
+			}()
+
+			err := ss.service.Start(ctx)
+			if err != nil {
+				ss.mu.Lock()
+				ss.state = StateFailed
+				ss.startErr = err
+				ss.mu.Unlock()
+			}
+			close(ss.startReturnedC)
+			registry.startC <- err
+		}(ss)
+	}
 }
 
-func (r *Registry) Wait(ctx context.Context) error {
+func (registry *Registry) Wait(ctx context.Context) error {
 	interrupt := make(chan os.Signal, 1)
 	signal.Notify(interrupt, syscall.SIGINT, syscall.SIGTERM)
 
 	select {
 	case <-ctx.Done():
-		r.logger.InfoContext(ctx, "caught context error, exiting", errors.Attr(ctx.Err()))
+		registry.logger.InfoContext(ctx, "caught context error, exiting", errors.Attr(ctx.Err()))
 	case s := <-interrupt:
-		r.logger.InfoContext(ctx, "caught interrupt signal, exiting", slog.Any("signal", s))
-	case err := <-r.startCh:
-		r.logger.ErrorContext(ctx, "caught service error, exiting", errors.Attr(err))
+		registry.logger.InfoContext(ctx, "caught interrupt signal, exiting", slog.Any("signal", s))
+	case err := <-registry.startC:
+		registry.logger.ErrorContext(ctx, "caught service error, exiting", errors.Attr(err))
 		return err
 	}
 
 	return nil
 }
 
-func (r *Registry) Stop(ctx context.Context) error {
-	for _, s := range r.services.GetInOrder() {
-		go func(s NamedService) {
-			r.logger.InfoContext(ctx, "stopping service", slog.Any("service", s.Name()))
-			err := s.Stop(ctx)
-			r.stopCh <- err
-		}(s)
+func (registry *Registry) Stop(ctx context.Context) error {
+	for _, ss := range registry.services {
+		go func(ss *serviceWithState) {
+			registry.logger.InfoContext(ctx, "stopping service", slog.Any("service", ss.service.Name()))
+			err := ss.service.Stop(ctx)
+			registry.stopC <- err
+		}(ss)
 	}
 
-	errs := make([]error, len(r.services.GetInOrder()))
-	for i := 0; i < len(r.services.GetInOrder()); i++ {
-		err := <-r.stopCh
+	errs := make([]error, len(registry.services))
+	for i := 0; i < len(registry.services); i++ {
+		err := <-registry.stopC
 		if err != nil {
 			errs = append(errs, err)
 		}
@@ -91,3 +168,83 @@ func (r *Registry) Stop(ctx context.Context) error {
 
 	return errors.Join(errs...)
 }
+
+// AwaitHealthy blocks until all services reach the RUNNING state or any service fails.
+func (registry *Registry) AwaitHealthy(ctx context.Context) error {
+	for _, ss := range registry.services {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-ss.healthyC:
+		case <-ss.startReturnedC:
+			ss.mu.RLock()
+			err := ss.startErr
+			ss.mu.RUnlock()
+			if err != nil {
+				return errors.Wrapf(err, errors.TypeInternal, ErrCodeServiceFailed, "service %q failed before becoming healthy", ss.service.Name())
+			}
+			return errors.Newf(errors.TypeInternal, ErrCodeServiceFailed, "service %q terminated before becoming healthy", ss.service.Name())
+		}
+	}
+	return nil
+}
+
+// ServicesByState returns a snapshot of the current state of all services.
+func (registry *Registry) ServicesByState() map[State][]Name {
+	result := make(map[State][]Name)
+	for _, ss := range registry.services {
+		state := ss.getState()
+		result[state] = append(result[state], ss.service.Name())
+	}
+	return result
+}
+
+// IsHealthy returns true if all services are in the RUNNING state.
+func (registry *Registry) IsHealthy() bool {
+	for _, ss := range registry.services {
+		if ss.getState() != StateRunning {
+			return false
+		}
+	}
+	return true
+}
+
+// detectCyclicDeps returns an error listing all dependency cycles found using
+// gonum's Tarjan SCC algorithm.
+func detectCyclicDeps(services []*serviceWithState) error {
+	nameToID := make(map[Name]int64, len(services))
+	idToName := make(map[int64]Name, len(services))
+	for i, ss := range services {
+		id := int64(i)
+		nameToID[ss.service.Name()] = id
+		idToName[id] = ss.service.Name()
+	}
+
+	g := simple.NewDirectedGraph()
+	for _, ss := range services {
+		g.AddNode(simple.Node(nameToID[ss.service.Name()]))
+	}
+	for _, ss := range services {
+		fromID := nameToID[ss.service.Name()]
+		for _, dep := range ss.dependsOn {
+			g.SetEdge(simple.Edge{F: simple.Node(fromID), T: simple.Node(nameToID[dep])})
+		}
+	}
+
+	if _, err := topo.Sort(g); err == nil {
+		return nil
+	}
+
+	var cycles [][]Name
+	for _, scc := range topo.TarjanSCC(g) {
+		if len(scc) > 1 {
+			cycle := make([]Name, len(scc))
+			for i, n := range scc {
+				cycle[i] = idToName[n.ID()]
+			}
+			cycles = append(cycles, cycle)
+		}
+	}
+
+	return errors.Newf(errors.TypeInvalidInput, ErrCodeInvalidRegistry, "dependency cycles detected: %v", cycles)
+}

pkg/factory/registry_test.go

@@ -5,7 +5,10 @@ import (
 	"log/slog"
 	"sync"
 	"testing"
+	"time"
 
+	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
@@ -28,11 +31,46 @@ func (s *tservice) Stop(_ context.Context) error {
 	return nil
 }
 
+type healthyTestService struct {
+	tservice
+	healthyC chan struct{}
+}
+
+func newHealthyTestService(t *testing.T) *healthyTestService {
+	t.Helper()
+	return &healthyTestService{
+		tservice: tservice{c: make(chan struct{})},
+		healthyC: make(chan struct{}),
+	}
+}
+
+func (s *healthyTestService) Healthy() <-chan struct{} {
+	return s.healthyC
+}
+
+// failingHealthyService implements Healthy but fails before signaling healthy.
+type failingHealthyService struct {
+	healthyC chan struct{}
+	err      error
+}
+
+func (s *failingHealthyService) Start(_ context.Context) error {
+	return s.err
+}
+
+func (s *failingHealthyService) Stop(_ context.Context) error {
+	return nil
+}
+
+func (s *failingHealthyService) Healthy() <-chan struct{} {
+	return s.healthyC
+}
+
 func TestRegistryWith2Services(t *testing.T) {
 	s1 := newTestService(t)
 	s2 := newTestService(t)
 
-	registry, err := NewRegistry(slog.New(slog.DiscardHandler), NewNamedService(MustNewName("s1"), s1), NewNamedService(MustNewName("s2"), s2))
+	registry, err := NewRegistry(context.Background(), slog.New(slog.DiscardHandler), NewNamedService(MustNewName("s1"), s1), NewNamedService(MustNewName("s2"), s2))
 	require.NoError(t, err)
 
 	ctx, cancel := context.WithCancel(context.Background())
@@ -41,8 +79,8 @@ func TestRegistryWith2Services(t *testing.T) {
 	go func() {
 		defer wg.Done()
 		registry.Start(ctx)
-		require.NoError(t, registry.Wait(ctx))
-		require.NoError(t, registry.Stop(ctx))
+		assert.NoError(t, registry.Wait(ctx))
+		assert.NoError(t, registry.Stop(ctx))
 	}()
 	cancel()
 
@@ -53,7 +91,7 @@ func TestRegistryWith2ServicesWithoutWait(t *testing.T) {
 	s1 := newTestService(t)
 	s2 := newTestService(t)
 
-	registry, err := NewRegistry(slog.New(slog.DiscardHandler), NewNamedService(MustNewName("s1"), s1), NewNamedService(MustNewName("s2"), s2))
+	registry, err := NewRegistry(context.Background(), slog.New(slog.DiscardHandler), NewNamedService(MustNewName("s1"), s1), NewNamedService(MustNewName("s2"), s2))
 	require.NoError(t, err)
 
 	ctx := context.Background()
@@ -62,8 +100,245 @@ func TestRegistryWith2ServicesWithoutWait(t *testing.T) {
 	go func() {
 		defer wg.Done()
 		registry.Start(ctx)
-		require.NoError(t, registry.Stop(ctx))
+		assert.NoError(t, registry.Stop(ctx))
 	}()
 
 	wg.Wait()
 }
+
+func TestServiceStateTransitions(t *testing.T) {
+	s1 := newTestService(t)
+
+	registry, err := NewRegistry(context.Background(), slog.New(slog.DiscardHandler), NewNamedService(MustNewName("s1"), s1))
+	require.NoError(t, err)
+
+	ctx := context.Background()
+	registry.Start(ctx)
+
+	require.NoError(t, registry.AwaitHealthy(ctx))
+
+	byState := registry.ServicesByState()
+	assert.Len(t, byState[StateRunning], 1)
+	assert.True(t, registry.IsHealthy())
+
+	assert.NoError(t, registry.Stop(ctx))
+}
+
+func TestServiceStateWithHealthy(t *testing.T) {
+	s1 := newHealthyTestService(t)
+
+	registry, err := NewRegistry(context.Background(), slog.New(slog.DiscardHandler), NewNamedService(MustNewName("s1"), s1))
+	require.NoError(t, err)
+
+	ctx := context.Background()
+	registry.Start(ctx)
+
+	// Poll until STARTING state is observed
+	require.Eventually(t, func() bool {
+		byState := registry.ServicesByState()
+		return len(byState[StateStarting]) == 1
+	}, time.Second, time.Millisecond)
+	assert.False(t, registry.IsHealthy())
+
+	// Signal healthy
+	close(s1.healthyC)
+
+	require.NoError(t, registry.AwaitHealthy(ctx))
+	assert.True(t, registry.IsHealthy())
+
+	byState := registry.ServicesByState()
+	assert.Len(t, byState[StateRunning], 1)
+
+	assert.NoError(t, registry.Stop(ctx))
+}
+
+func TestAwaitHealthy(t *testing.T) {
+	s1 := newTestService(t)
+	s2 := newTestService(t)
+
+	registry, err := NewRegistry(context.Background(), slog.New(slog.DiscardHandler), NewNamedService(MustNewName("s1"), s1), NewNamedService(MustNewName("s2"), s2))
+	require.NoError(t, err)
+
+	ctx := context.Background()
+	registry.Start(ctx)
+
+	assert.NoError(t, registry.AwaitHealthy(ctx))
+	assert.True(t, registry.IsHealthy())
+
+	assert.NoError(t, registry.Stop(ctx))
+}
+
+func TestAwaitHealthyWithFailure(t *testing.T) {
+	s1 := &failingHealthyService{
+		healthyC: make(chan struct{}),
+		err:      errors.Newf(errors.TypeInternal, errors.CodeInternal,"startup failed"),
+	}
+
+	registry, err := NewRegistry(context.Background(), slog.New(slog.DiscardHandler), NewNamedService(MustNewName("s1"), s1))
+	require.NoError(t, err)
+
+	ctx := context.Background()
+	registry.Start(ctx)
+
+	err = registry.AwaitHealthy(ctx)
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "startup failed")
+}
+
+func TestServicesByState(t *testing.T) {
+	s1 := newTestService(t)
+	s2 := newHealthyTestService(t)
+
+	registry, err := NewRegistry(context.Background(), slog.New(slog.DiscardHandler), NewNamedService(MustNewName("s1"), s1), NewNamedService(MustNewName("s2"), s2))
+	require.NoError(t, err)
+
+	ctx := context.Background()
+	registry.Start(ctx)
+
+	// Wait for s1 to be running (no Healthy interface) and s2 to be starting
+	require.Eventually(t, func() bool {
+		byState := registry.ServicesByState()
+		return len(byState[StateRunning]) == 1 && len(byState[StateStarting]) == 1
+	}, time.Second, time.Millisecond)
+
+	// Make s2 healthy
+	close(s2.healthyC)
+
+	require.NoError(t, registry.AwaitHealthy(ctx))
+	byState := registry.ServicesByState()
+	assert.Len(t, byState[StateRunning], 2)
+
+	assert.NoError(t, registry.Stop(ctx))
+}
+
+func TestDependsOnStartsAfterDependency(t *testing.T) {
+	s1 := newHealthyTestService(t)
+	s2 := newTestService(t)
+
+	// s2 depends on s1
+	registry, err := NewRegistry(
+		context.Background(),
+		slog.New(slog.DiscardHandler),
+		NewNamedService(MustNewName("s1"), s1),
+		NewNamedService(MustNewName("s2"), s2, MustNewName("s1")),
+	)
+	require.NoError(t, err)
+
+	ctx := context.Background()
+	registry.Start(ctx)
+
+	// s2 should still be STARTING because s1 hasn't become healthy yet
+	require.Eventually(t, func() bool {
+		byState := registry.ServicesByState()
+		return len(byState[StateStarting]) == 2
+	}, time.Second, time.Millisecond)
+
+	// Make s1 healthy — s2 should then start and become RUNNING
+	close(s1.healthyC)
+
+	assert.NoError(t, registry.AwaitHealthy(ctx))
+	assert.True(t, registry.IsHealthy())
+
+	assert.NoError(t, registry.Stop(ctx))
+}
+
+func TestDependsOnFailsWhenDependencyFails(t *testing.T) {
+	s1 := &failingHealthyService{
+		healthyC: make(chan struct{}),
+		err:      errors.Newf(errors.TypeInternal, errors.CodeInternal,"s1 crashed"),
+	}
+	s2 := newTestService(t)
+
+	// s2 depends on s1
+	registry, err := NewRegistry(
+		context.Background(),
+		slog.New(slog.DiscardHandler),
+		NewNamedService(MustNewName("s1"), s1),
+		NewNamedService(MustNewName("s2"), s2, MustNewName("s1")),
+	)
+	require.NoError(t, err)
+
+	ctx := context.Background()
+	registry.Start(ctx)
+
+	// Both should eventually fail
+	assert.Eventually(t, func() bool {
+		byState := registry.ServicesByState()
+		return len(byState[StateFailed]) == 2
+	}, time.Second, time.Millisecond)
+}
+
+func TestDependsOnUnknownServiceIsIgnored(t *testing.T) {
+	s1 := newTestService(t)
+
+	// Unknown dependency is logged and ignored, not an error.
+	registry, err := NewRegistry(
+		context.Background(),
+		slog.New(slog.DiscardHandler),
+		NewNamedService(MustNewName("s1"), s1, MustNewName("unknown")),
+	)
+	require.NoError(t, err)
+
+	ctx := context.Background()
+	registry.Start(ctx)
+
+	assert.NoError(t, registry.AwaitHealthy(ctx))
+	assert.True(t, registry.IsHealthy())
+
+	assert.NoError(t, registry.Stop(ctx))
+}
+
+func TestServiceStateFailed(t *testing.T) {
+	s1 := &failingHealthyService{
+		healthyC: make(chan struct{}),
+		err:      errors.Newf(errors.TypeInternal, errors.CodeInternal,"fatal error"),
+	}
+
+	registry, err := NewRegistry(context.Background(), slog.New(slog.DiscardHandler), NewNamedService(MustNewName("s1"), s1))
+	require.NoError(t, err)
+
+	ctx := context.Background()
+	registry.Start(ctx)
+
+	// Wait for the service to fail
+	assert.Eventually(t, func() bool {
+		byState := registry.ServicesByState()
+		return len(byState[StateFailed]) == 1
+	}, time.Second, time.Millisecond)
+	assert.False(t, registry.IsHealthy())
+}
+
+func TestDependsOnSelfDependencyIsIgnored(t *testing.T) {
+	s1 := newTestService(t)
+
+	// Self-dependency is logged and ignored.
+	registry, err := NewRegistry(
+		context.Background(),
+		slog.New(slog.DiscardHandler),
+		NewNamedService(MustNewName("s1"), s1, MustNewName("s1")),
+	)
+	require.NoError(t, err)
+
+	ctx := context.Background()
+	registry.Start(ctx)
+
+	assert.NoError(t, registry.AwaitHealthy(ctx))
+	assert.True(t, registry.IsHealthy())
+
+	assert.NoError(t, registry.Stop(ctx))
+}
+
+func TestDependsOnCycleReturnsError(t *testing.T) {
+	s1 := newTestService(t)
+	s2 := newTestService(t)
+
+	// A -> B and B -> A is a cycle.
+	_, err := NewRegistry(
+		context.Background(),
+		slog.New(slog.DiscardHandler),
+		NewNamedService(MustNewName("s1"), s1, MustNewName("s2")),
+		NewNamedService(MustNewName("s2"), s2, MustNewName("s1")),
+	)
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "dependency cycles detected")
+}

pkg/factory/service.go

@@ -2,30 +2,81 @@ package factory
 
 import "context"
 
+// Service is the core lifecycle interface for long-running services.
 type Service interface {
 	// Starts a service. It should block and should not return until the service is stopped or it fails.
 	Start(context.Context) error
+
 	// Stops a service.
 	Stop(context.Context) error
 }
 
-type NamedService interface {
-	Named
-	Service
+// Healthy is an optional interface that services can implement to signal
+// when they have completed startup and are ready to serve.
+// Services that do not implement this interface are considered healthy
+// immediately after Start() is called.
+type Healthy interface {
+	// Healthy returns a channel that is closed when the service is healthy.
+	Healthy() <-chan struct{}
 }
 
-type namedService struct {
-	name Name
+// ServiceWithHealthy is a Service that explicitly signals when it is healthy.
+type ServiceWithHealthy interface {
 	Service
+	Healthy
+}
+
+// NamedService is a Service with a Name and optional dependencies.
+type NamedService interface {
+	Named
+	ServiceWithHealthy
+	// DependsOn returns the names of services that must be healthy before this service starts.
+	DependsOn() []Name
+}
+
+// closedC is a pre-closed channel returned for services that don't implement Healthy.
+var closedC = func() chan struct{} {
+	c := make(chan struct{})
+	close(c)
+	return c
+}()
+
+type namedService struct {
+	name      Name
+	dependsOn []Name
+	service   Service
+}
+
+// NewNamedService wraps a Service with a Name and optional dependency names.
+func NewNamedService(name Name, service Service, dependsOn ...Name) NamedService {
+	return &namedService{
+		name:      name,
+		dependsOn: dependsOn,
+		service:   service,
+	}
 }
 
 func (s *namedService) Name() Name {
 	return s.name
 }
 
-func NewNamedService(name Name, service Service) NamedService {
-	return &namedService{
-		name:    name,
-		Service: service,
-	}
+func (s *namedService) DependsOn() []Name {
+	return s.dependsOn
+}
+
+func (s *namedService) Start(ctx context.Context) error {
+	return s.service.Start(ctx)
+}
+
+func (s *namedService) Stop(ctx context.Context) error {
+	return s.service.Stop(ctx)
+}
+
+// Healthy delegates to the underlying service if it implements Healthy,
+// otherwise returns an already-closed channel (immediately healthy).
+func (s *namedService) Healthy() <-chan struct{} {
+	if h, ok := s.service.(Healthy); ok {
+		return h.Healthy()
+	}
+	return closedC
 }

pkg/factory/state.go

@@ -0,0 +1,75 @@
+package factory
+
+import "sync"
+
+// State represents the lifecycle state of a service.
+type State struct {
+	s string
+}
+
+func (s State) String() string {
+	return s.s
+}
+
+// MarshalText implements encoding.TextMarshaler so State can be used as a JSON map key.
+func (s State) MarshalText() ([]byte, error) {
+	return []byte(s.s), nil
+}
+
+var (
+	StateStarting = State{"starting"}
+	StateRunning  = State{"running"}
+	StateFailed   = State{"failed"}
+)
+
+// serviceWithState wraps a NamedService with thread-safe state tracking.
+type serviceWithState struct {
+	// service is the underlying named service.
+	service NamedService
+
+	// dependsOn is the validated subset of declared dependencies that exist in the registry.
+	dependsOn []Name
+
+	// mu protects state and startErr from concurrent access.
+	mu sync.RWMutex
+
+	// state is the current lifecycle state of the service.
+	state State
+
+	// healthyC is closed when the service transitions to StateRunning.
+	healthyC chan struct{}
+
+	// startReturnedC is closed when Start() returns, whether with nil or an error.
+	startReturnedC chan struct{}
+
+	// startErr is the error returned by Start(), or nil if it returned successfully.
+	startErr error
+}
+
+func newServiceWithState(service NamedService) *serviceWithState {
+	return &serviceWithState{
+		service:        service,
+		state:          StateStarting,
+		healthyC:       make(chan struct{}),
+		startReturnedC: make(chan struct{}),
+	}
+}
+
+func (ss *serviceWithState) setState(state State) {
+	ss.mu.Lock()
+	defer ss.mu.Unlock()
+	ss.state = state
+	if state == StateRunning {
+		select {
+		case <-ss.healthyC:
+		default:
+			close(ss.healthyC)
+		}
+	}
+}
+
+func (ss *serviceWithState) getState() State {
+	ss.mu.RLock()
+	defer ss.mu.RUnlock()
+	return ss.state
+}

pkg/modules/user/impluser/service.go

@@ -23,6 +23,7 @@ type service struct {
 	authz     authz.AuthZ
 	config    user.RootConfig
 	stopC     chan struct{}
+	healthyC  chan struct{}
 }
 
 func NewService(
@@ -42,12 +43,14 @@ func NewService(
 		orgGetter: orgGetter,
 		authz:     authz,
 		config:    config,
-		stopC:     make(chan struct{}),
+		stopC:    make(chan struct{}),
+		healthyC: make(chan struct{}),
 	}
 }
 
 func (s *service) Start(ctx context.Context) error {
 	if !s.config.Enabled {
+		close(s.healthyC)
 		<-s.stopC
 		return nil
 	}
@@ -59,6 +62,7 @@ func (s *service) Start(ctx context.Context) error {
 		err := s.reconcile(ctx)
 		if err == nil {
 			s.settings.Logger().InfoContext(ctx, "root user reconciliation completed successfully")
+			close(s.healthyC)
 			<-s.stopC
 			return nil
 		}
@@ -74,6 +78,10 @@ func (s *service) Start(ctx context.Context) error {
 	}
 }
 
+func (s *service) Healthy() <-chan struct{} {
+	return s.healthyC
+}
+
 func (s *service) Stop(ctx context.Context) error {
 	close(s.stopC)
 	return nil

pkg/modules/user/service.go

@@ -3,5 +3,5 @@ package user
 import "github.com/SigNoz/signoz/pkg/factory"
 
 type Service interface {
-	factory.Service
+	factory.ServiceWithHealthy
 }

pkg/signoz/handler.go

@@ -55,6 +55,7 @@ type Handlers struct {
 	ZeusHandler           zeus.Handler
 	QuerierHandler        querier.Handler
 	ServiceAccountHandler serviceaccount.Handler
+	RegistryHandler       factory.Handler
 }
 
 func NewHandlers(
@@ -69,6 +70,7 @@ func NewHandlers(
 	telemetryMetadataStore telemetrytypes.MetadataStore,
 	authz authz.AuthZ,
 	zeusService zeus.Zeus,
+	registryHandler factory.Handler,
 ) Handlers {
 	return Handlers{
 		SavedView:             implsavedview.NewHandler(modules.SavedView),
@@ -88,5 +90,6 @@ func NewHandlers(
 		ZeusHandler:           zeus.NewHandler(zeusService, licensing),
 		QuerierHandler:        querierHandler,
 		ServiceAccountHandler: implserviceaccount.NewHandler(modules.ServiceAccount),
+		RegistryHandler:       registryHandler,
 	}
 }

pkg/signoz/handler_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/SigNoz/signoz/pkg/alertmanager/nfmanager/nfmanagertest"
 	"github.com/SigNoz/signoz/pkg/alertmanager/signozalertmanager"
 	"github.com/SigNoz/signoz/pkg/emailing/emailingtest"
+	"github.com/SigNoz/signoz/pkg/factory"
 	"github.com/SigNoz/signoz/pkg/factory/factorytest"
 	"github.com/SigNoz/signoz/pkg/flagger"
 	"github.com/SigNoz/signoz/pkg/instrumentation/instrumentationtest"
@@ -55,7 +56,8 @@ func TestNewHandlers(t *testing.T) {
 	modules := NewModules(sqlstore, tokenizer, emailing, providerSettings, orgGetter, alertmanager, nil, nil, nil, nil, nil, nil, nil, queryParser, Config{}, dashboardModule, userGetter, userRoleStore)
 
 	querierHandler := querier.NewHandler(providerSettings, nil, nil)
-	handlers := NewHandlers(modules, providerSettings, nil, querierHandler, nil, nil, nil, nil, nil, nil, nil)
+	registryHandler := factory.NewHandler(nil)
+	handlers := NewHandlers(modules, providerSettings, nil, querierHandler, nil, nil, nil, nil, nil, nil, nil, registryHandler)
 	reflectVal := reflect.ValueOf(handlers)
 	for i := 0; i < reflectVal.NumField(); i++ {
 		f := reflectVal.Field(i)

pkg/signoz/openapi.go

@@ -10,6 +10,7 @@ import (
 	"github.com/SigNoz/signoz/pkg/apiserver"
 	"github.com/SigNoz/signoz/pkg/apiserver/signozapiserver"
 	"github.com/SigNoz/signoz/pkg/authz"
+	"github.com/SigNoz/signoz/pkg/factory"
 	"github.com/SigNoz/signoz/pkg/flagger"
 	"github.com/SigNoz/signoz/pkg/gateway"
 	"github.com/SigNoz/signoz/pkg/global"
@@ -61,6 +62,7 @@ func NewOpenAPI(ctx context.Context, instrumentation instrumentation.Instrumenta
 		struct{ zeus.Handler }{},
 		struct{ querier.Handler }{},
 		struct{ serviceaccount.Handler }{},
+		struct{ factory.Handler }{},
 	).New(ctx, instrumentation.ToProviderSettings(), apiserver.Config{})
 	if err != nil {
 		return nil, err

pkg/signoz/provider.go

@@ -277,6 +277,7 @@ func NewAPIServerProviderFactories(orgGetter organization.Getter, authz authz.Au
 			handlers.ZeusHandler,
 			handlers.QuerierHandler,
 			handlers.ServiceAccountHandler,
+			handlers.RegistryHandler,
 		),
 	)
 }

pkg/signoz/signoz.go

@@ -422,21 +422,6 @@ func New(
 	// Initialize the querier handler via callback (allows EE to decorate with anomaly detection)
 	querierHandler := querierHandlerCallback(providerSettings, querier, analytics)
 
-	// Initialize all handlers for the modules
-	handlers := NewHandlers(modules, providerSettings, analytics, querierHandler, licensing, global, flagger, gateway, telemetryMetadataStore, authz, zeus)
-
-	// Initialize the API server
-	apiserver, err := factory.NewProviderFromNamedMap(
-		ctx,
-		providerSettings,
-		config.APIServer,
-		NewAPIServerProviderFactories(orgGetter, authz, modules, handlers),
-		"signoz",
-	)
-	if err != nil {
-		return nil, err
-	}
-
 	// Create a list of all stats collectors
 	statsCollectors := []statsreporter.StatsCollector{
 		alertmanager,
@@ -463,6 +448,7 @@ func New(
 	}
 
 	registry, err := factory.NewRegistry(
+		ctx,
 		instrumentation.Logger(),
 		factory.NewNamedService(factory.MustNewName("instrumentation"), instrumentation),
 		factory.NewNamedService(factory.MustNewName("pprof"), pprofService),
@@ -472,7 +458,23 @@ func New(
 		factory.NewNamedService(factory.MustNewName("statsreporter"), statsReporter),
 		factory.NewNamedService(factory.MustNewName("tokenizer"), tokenizer),
 		factory.NewNamedService(factory.MustNewName("authz"), authz),
-		factory.NewNamedService(factory.MustNewName("user"), userService),
+		factory.NewNamedService(factory.MustNewName("user"), userService, factory.MustNewName("authz")),
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	// Initialize all handlers for the modules
+	registryHandler := factory.NewHandler(registry)
+	handlers := NewHandlers(modules, providerSettings, analytics, querierHandler, licensing, global, flagger, gateway, telemetryMetadataStore, authz, zeus, registryHandler)
+
+	// Initialize the API server (after registry so it can access service health)
+	apiserverInstance, err := factory.NewProviderFromNamedMap(
+		ctx,
+		providerSettings,
+		config.APIServer,
+		NewAPIServerProviderFactories(orgGetter, authz, modules, handlers),
+		"signoz",
 	)
 	if err != nil {
 		return nil, err
@@ -490,7 +492,7 @@ func New(
 		Prometheus:             prometheus,
 		Alertmanager:           alertmanager,
 		Querier:                querier,
-		APIServer:              apiserver,
+		APIServer:              apiserverInstance,
 		Zeus:                   zeus,
 		Licensing:              licensing,
 		Emailing:               emailing,

tests/integration/fixtures/signoz.py

@@ -108,16 +108,24 @@ def create_signoz(
             for attempt in range(10):
                 try:
                     response = requests.get(
-                        f"http://{container.get_container_host_ip()}:{container.get_exposed_port(8080)}/api/v1/health",
+                        f"http://{container.get_container_host_ip()}:{container.get_exposed_port(8080)}/api/v2/healthz",
                         timeout=2,
                     )
                     if response.status_code == HTTPStatus.OK:
                         return
-                except Exception:  # pylint: disable=broad-exception-caught
-                    logger.info(
-                        "Attempt %s at readiness check for SigNoz container %s failed, going to retry ...",
+                    if response.status_code == HTTPStatus.SERVICE_UNAVAILABLE:
+                        logger.error(
+                            "Attempt %s: SigNoz container %s not ready yet:\n%s",
+                            attempt + 1,
+                            container,
+                            response.text,
+                        )
+                except Exception as e:  # pylint: disable=broad-exception-caught
+                    logger.error(
+                        "Attempt %s at readiness check for SigNoz container %s failed: %s",
                         attempt + 1,
                         container,
+                        e,
                     )
                 time.sleep(2)
             raise TimeoutError("timeout exceeded while waiting")

tests/integration/src/bootstrap/setup.py

@@ -1,3 +1,4 @@
+import logging
 from http import HTTPStatus
 
 import numpy as np
@@ -5,14 +6,21 @@ import requests
 
 from fixtures import types
 
+logger = logging.getLogger(__name__)
+
 
 def test_setup(signoz: types.SigNoz) -> None:
     response = requests.get(
         signoz.self.host_configs["8080"].get("/api/v1/version"), timeout=2
     )
-
     assert response.status_code == HTTPStatus.OK
 
+    healthz = requests.get(
+        signoz.self.host_configs["8080"].get("/api/v2/healthz"), timeout=2
+    )
+    logger.info("healthz response: %s", healthz.json())
+    assert healthz.status_code == HTTPStatus.OK
+
 
 def test_telemetry_databases_exist(signoz: types.SigNoz) -> None:
     arr: np.ndarray = signoz.telemetrystore.conn.query_np("SHOW DATABASES")