Service registry enum

Canonical service-name enum — genieai-* service names, OTel attributes, and image tags.

Purpose

The canonical enum of service names used in OTel attributes, VictoriaLogs filters, Kong routes, and Docker swarm service names. The Python enum lives in genie-ai-overlay/core/constants.py.

Service registry

Note: The “Enum value” column is a logical role used in code and ops queries — there is no service-name enum in genie-ai-overlay/core/constants.py (only the OPEA service-type enum ServiceType lives there). The OTel service.name column shows the value passed to setup_tracing(...) for instrumented services, or the env-var / container name for uninstrumented ones. “Docker service” is the block name in docker-compose.yaml; in Docker Swarm it is prefixed by the stack name (e.g. genieai_chatqna-xeon-backend-server).

Role	OTel `service.name`	Docker service	Image
`chatqna`	`genieai-chatqna`	`chatqna-xeon-backend-server`	`genie-ai-chatqna-server`
`retriever`	`genieai-retriever`	`retriever-arango-service`	`genie-ai-retriever-arango`
`reranker`	`genieai-reranker`	`reranker`	`genie-ai-reranker`
`embedding`	(external — TEI)	`embedding`	`genie-ai-embedding` (TEI `text-embeddings-inference`)
`textgen`	(external)	`textgen`	`genie-ai-textgen`
`vllm`	(external)	`vllm`	`vllm/vllm-openai`
`dataprep`	`genieai-dataprep`	`dataprep-arango-service`	`genie-ai-dataprep-arango`
`translation`	(part of chatqna)	`translation`	`opea/translation:1.5`
`doc-repo`	`document-repository`	`document-repository`	`genie-ai-document-repository`
`backend`	`backend`	`backend`	`genie-ai-backend`
`frontend`	(not instrumented)	`frontend`	`genie-ai-frontend`
`kong`	(Kong OTel plugin)	`kong`	`kong:3.9.3`
`nginx`	(not instrumented)	`nginx`	`genie-ai-nginx`
`keycloak`	(not instrumented)	`keycloak`	`quay.io/keycloak/keycloak:26.7.0`
`arangodb`	(not instrumented)	`arango-vector-db`	`arangodb/arangodb:3.12.4`
`redis`	(not instrumented)	`redis-cache`	`redis:7-alpine`
`clamav`	(not instrumented)	`clamav`	`clamav/clamav:stable-debian`
`otel-collector`	`otel-collector`	`otel-collector`	`otel/opentelemetry-collector-contrib:0.152.0`
`victoriametrics`	`victoriametrics`	`victoriametrics`	`victoriametrics/victoria-metrics:v1.138.0`
`victorialogs`	`victorialogs`	`victorialogs`	`victoriametrics/victoria-logs:v1.50.0`
`victoriatraces`	`victoriatraces`	`victoriatraces`	`victoriametrics/victoria-traces:v0.9.2`
`grafana`	`grafana`	`grafana`	`grafana/grafana:12.4`

Swarm label convention

The Swarm label convention documented in earlier docs (genieai.service.name, genieai.component, genieai.persona) is not currently applied in docker-compose.yaml. If the OTel Collector uses those labels for resource attribute enrichment, that enrichment is inactive today — verify against configs/otel/config.yaml before relying on it.

VictoriaLogs query examples

{service.name="genieai-chatqna"} | error
{service.name=~"genieai-(backend|chatqna|retriever)"}
{service.name="genieai-vllm"} AND _msg:"oom"

Adding a new service

Add the enum to genie-ai-overlay/core/constants.py.
Add the OTel service.name to the new service’s OTEL_SERVICE_NAME env var.
Add the Swarm label to the service’s docker-compose.yaml block.
Document it on this page and in Architecture → OPEA microservices.

Last modified October 16, 2026: fix(ansible): keep the config dirs root-owned; sweep the image-count docs (a833ae2d9)