How clouddetail/odigos works
Project type and purpose
• This is a Kubernetes-native observability platform (a modified Odigos) that provides language-agnostic auto-instrumentation, dynamic agent injection (via webhooks and eBPF), data collection, on-cluster collectors management (autoscaler & scheduler), a CLI, and a web UI.
• It leverages CustomResourceDefinitions (CRDs) and multiple controllers/operators written in Go, plus a Next.js frontend and a Go HTTP API layer.
File structure
• Top-level directories:
• agents: custom Node.js agent code
• api: Kubernetes API types/CRDs and codegen
• autoscaler, scheduler, instrumentor: three distinct controllers/operators
• collector: customized OpenTelemetry Collector plus exporters & processors
• common, k8sutils: shared libraries
• cli: command-line interface
• frontend: Go HTTP server + Next.js web UI
• odiglet: sidecar/eBPF loader for auto-instrumentation
• opampserver: OpAMP control-plane server
• procdiscovery: process-level language detectors
• Each “service” folder contains its own main.go, controllers, Makefile/Dockerfile, and go.mod.
README insights
• Purpose: inject agents into workloads (Java, Python, Node.js, .NET, Go via eBPF) without code changes, emit data in OTLP format, allow custom endpoints via env vars.
• Features: CLI-driven install, web UI for managing “CollectorsGroup” CRs, autoscaling collectors, no hardwired built-in collector (user supplies endpoints).
a. Main components
• Kubernetes API Server & etcd
• CLI (external client)
• Frontend Service: Go HTTP API + Next.js UI
• Instrumentor Operator (MutatingWebhook + controller)
• Odiglet DaemonSet/Init-container & sidecar code (eBPF loader + agents)
• OpAMP Server (control-plane for collectors)
• Autoscaler Operator
• Scheduler Operator
• OpenTelemetry Collector Deployment(s)
• Destination Backends (external OTLP endpoints or hosted services)
b. Relationships & interactions
1. CLI ↔ Kubernetes API: installs CRDs, InstrumentationInstance, OdigosConfiguration, CollectorsGroup, Destinations, etc.
2. Frontend ↔ Go API ↔ Kubernetes API: reads/writes CRDs; uses kube watchers
3. Instrumentor Webhook intercepts PodCreate, mutates Pod spec to inject odiglet sidecar/init container
4. Odiglet inside target Pod collects spans/traces via agent hooks or eBPF, forwards telemetry to configured endpoint (OpAMP server or custom OTLP)
5. Collector(s) (Deployed via CollectorsGroup CR) receive OTLP, apply processors/exporters (common/config), send to Destination Backends
6. OpAMP Server aggregates telemetry metrics, provides control-plane to Autoscaler
7. Autoscaler Operator reads metrics from OpAMP Server, updates HPA on Collector Deployment
8. Scheduler Operator watches CollectorsGroup CRs, binds Collector Pods to nodes via scheduling constraints
c. Architectural patterns & principles
• Kubernetes operator pattern (CRD + controllers)
• MutatingAdmissionWebhook for zero-downtime agent injection
• Sidecar/Init-container pattern for instrumentation (odiglet)
• Microservices: each Go service is independently deployable
• Declarative configuration via CRDs
• Separation of concerns: instrumentation (instrumentor + odiglet), data plane (collector), control plane (opampserver + autoscaler + scheduler), user interfaces (CLI + frontend)
d. Key technologies & libraries
• Go modules, client-go, controller-runtime
• Kubernetes CRDs for custom resources
• OpenTelemetry Collector core, processors, exporters
• eBPF via odiglet pkg/ebpf
• Next.js, React, SWR for frontend
• OpAMP (Open-Agent-Management-Protocol)