How hypertrace/config-service works
Project type and purpose
• Type: A Gradle‐based multi‐module Java microservice implementing a gRPC API for managing configurations (user prefs, filters, ingestion configs, etc.)
• Purpose: Provide a unified “config‐service” that stores, serves, versions, audits, and publishes change‐events for various domain‐specific configurations (alerting, labeling, notification, partitioner, spaces, span‐processing).
File structure to find logical layers
Top‐level modules:
• alerting‐config‐service‐api / impl
• config‐object‐store
• config‐proto‐converter
• config‐service‐api
• config‐service‐impl
• config‐service (the main executable)
• config‐validation‐utils
• config‐service‐change‐event‐api / generator
• config‐service‐factory
• domain modules (label‐application‐rule, labels, notification‐channel, notification‐rule, partitioner, spaces, span‐processing) each split into api + impl
• helm chart for deployment
Patterns:
• Modular, domain‐driven services under one codebase
• gRPC‐first API definition in “‐api” modules, Java implementations in “‐impl” modules
• Factory module to wire up domain services into one server
• Converter & validation utility modules for shared logic
• Event‐generator module to emit change events
Readme insights
• Single Docker image with all services (built via ./gradlew dockerBuildImages)
• Main API defined in config‐service‐api/config_service.proto
• Uses gRPC + Protobuf on the wire
• Integration tests verify end‐to‐end behavior
Main components
a. Client/Consumer Layer
– gRPC clients (other Hypertrace services or UIs)
b. API Layer
– config‐service‐api: Protobuf definitions
– alerting/labels/notification/etc. APIs
c. Service Runtime Layer (config‐service)
– ConfigServiceGrpcImpl (entry point)
– ConfigServiceFactory: wires up individual domain service impls
– Domain Service Modules (each implements its own ConfigServiceImpl)
• alerting‐config‐service‐impl
• labels‐config‐service‐impl
• notification‐channel/notification‐rule‐config‐service‐impl
• partitioner‐config‐service‐impl
• spaces‐config‐service‐impl
• span‐processing‐config‐service‐impl
d. Helper/Utility Modules
– config‐proto‐converter: DTO ↔ Proto mapping
– config‐validation‐utils: request validation logic
– config‐object‐store: generic object‐store abstraction
e. Persistence Layer
– DocumentConfigStore (backed by a NoSQL/Document DB—e.g., Couchbase, Cassandra, DynamoDB)
– ’store’ interfaces inside each domain impl
f. Eventing Layer
– config‐service‐change‐event‐api: event schema definitions
– config‐service‐change‐event‐generator: publishes events to Kafka (or another bus)
g. Operations / Deployment
– Docker image built by Gradle
– Helm chart (helm/Chart.yaml + templates): Kubernetes Deployment, Service, ConfigMap, Logging
Relationships and data flows
1) Client → gRPC (edge of system)
2) gRPC server → ConfigServiceGrpcImpl → ConfigServiceFactory
3) Factory → appropriate DomainServiceImpl
4) DomainServiceImpl →
a) proto‐converter for marshalling
b) validator for request checks
c) object‐store client for persistence
d) after write/update → change‐event generator
5) Persistence → Document DB
6) Change events → Kafka (or configured message bus)
7) Helm/K8s → deploys the Docker image and ConfigMaps
Architectural patterns & principles
• Modularization by domain (plug‐in style)
• “API first” via Protobuf/gRPC
• Factory pattern to assemble services in one server
• Separation of concerns: API, service logic, validation, conversion, persistence, eventing
• Event‐driven integration for config change notifications
– Clear component names matching module names
– Note on the bottom: build & deployment via Gradle → Docker → Helm/K8s
– Reflects each Gradle module’s role in the chain
– Shows how gRPC requests flow through factory & domain services
– Captures persistence and event‐driven integrations
– Illustrates the Kubernetes deployment topology via Helm