How miguelsmuller/lab-observability works
Project Type & Purpose
• This project is designed as an experimentation environment focused on observability. It includes two microservices – one written in Kotlin and another in Python – alongside a monitoring/observability platform, SigNoz.
• The goal is to demonstrate and learn about monitoring, distributed tracing, and centralized logging by instrumenting these microservices and integrating with SigNoz.
Analyzing the File Structure
• There are clearly two main application components:
– The “kotlin-app” directory hosts the Kotlin microservice, which follows a layered/hexagonal architecture pattern. Notice the separation into:
▪ Application entry point (KotlinAppApplication.kt)
▪ Adapters for incoming requests (controllers)
▪ Adapters for outgoing integrations (client, e.g., PythonAppClient)
▪ Environment-specific configurations in application-{env}.yaml.
– The “python-app” directory contains the Python microservice with its own Dockerfile, configuration (pyproject.toml), and tests.
• The presence of Dockerfiles in both subprojects along with a top-level “compose.yaml” suggests that container orchestration is a key aspect.
• Additionally, a “signoz” directory and a reference to SigNoz in the README indicate that a full observability stack is used for metrics, logs, and traces.
• Other files include build scripts (Gradle for Kotlin), submodules, and documentation (docs/ directory).
a. Main Components:
• Kotlin Microservice – “kotlin-app”
• Python Microservice – “python-app”
• Observability Platform – SigNoz (deployed via Docker Compose in the “signoz” directory)
• Additional components include:
▪ Docker Compose orchestration that brings up all containers.
▪ Subsystems within each microservice (e.g., controllers and client adapters in Kotlin).
b. Relationships and Interactions:
• Both microservices are instrumented to send metrics, traces, and logs to the SigNoz observability platform.
• The Kotlin microservice further structures its code into inbound (controllers) and outbound (client integrator to Python) adapters, reflecting a hexagonal architecture.
• The deployment layer (Docker Compose) should be shown orchestrating the start-up of each container/service.
c. Architectural Patterns and Design Principles:
• Hexagonal (ports & adapters) architecture in the Kotlin service: clearly separate internal domain logic from external interfaces.
• Containerization and orchestration (Docker, Docker Compose) to manage the microservices and observability stack.
• Emphasis on observability: all components emit metrics, logs, and traces to SigNoz.
d. Relevant Technologies and Frameworks:
• Kotlin with Gradle for the Kotlin app.
• Python for another microservice using pyproject.toml (likely a framework like Flask/FastAPI, though not explicitly stated—review the “app” directory for clues).
• Docker files for containerization.
• SigNoz to aggregate observability data, using OpenTelemetry (OTel) instrumentation, as referenced by the documentation links.