# clouddetail/odigos architecture

> Architecture diagram of the GitHub repository clouddetail/odigos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/clouddetail/odigos
- Repository: https://github.com/clouddetail/odigos

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Users & Interfaces"
        U[User]:::external
        CLI["CLI"]:::control
        NextJS["Next.js UI"]:::frontend
        FrontendAPI["Frontend API"]:::control
    end

    U --> CLI
    U --> NextJS
    NextJS --> FrontendAPI
    CLI -->|"k8s API calls"| K8sAPI

    subgraph "Kubernetes Control Plane"
        K8sAPI["Kubernetes API Server"]:::k8s
        Etcd[(etcd)]:::k8s
        K8sAPI --> Etcd
    end

    CRDs["CRDs (InstrumentationInstance, OdigosConfiguration, CollectorsGroup, Destination)"]:::config
    K8sAPI --> CRDs
    FrontendAPI -->|"CRUD via kube client/watch"| CRDs
    CLI --> CRDs

    subgraph "Control-Plane Controllers"
        Instrumentor["Instrumentor Operator"]:::control
        Autoscaler["Autoscaler Operator"]:::control
        Scheduler["Scheduler Operator"]:::control
        Instrumentor --> CRDs
        Autoscaler --> CRDs
        Scheduler --> CRDs
        CRDs --> Instrumentor
        CRDs --> Autoscaler
        CRDs --> Scheduler
    end

    Pod["Pod Creation"]:::data
    Instrumentor -->|"MutatingWebhook"| Pod
    Pod --> MutatedPod["Mutated Pod"]:::data
    MutatedPod --> OdigletSidecar["Odiglet Sidecar"]:::data

    OdigletSidecar -->|"gRPC/HTTP OTLP"| OpAMP["OpAMP Server"]:::control
    OdigletSidecar -->|"gRPC/HTTP OTLP"| CollectorPods["OpenTelemetry Collector"]:::data

    subgraph "Collectors Data Plane"
        CollectorPods -->|"process & export"| Destination["Destination Backends"]:::external
        CollectorPods -->|"metrics"| OpAMP
    end

    OpAMP --> Autoscaler
    Autoscaler -->|"update HPA on Collector"| CollectorPods
    Scheduler -->|"scheduling constraints"| CollectorPods

    click CLI "https://github.com/clouddetail/odigos/blob/apo-v1.0.76/cli/main.go"
    click FrontendAPI "https://github.com/clouddetail/odigos/blob/apo-v1.0.76/frontend/main.go"
    click NextJS "https://github.com/clouddetail/odigos/tree/apo-v1.0.76/frontend/webapp/"
    click Instrumentor "https://github.com/clouddetail/odigos/blob/apo-v1.0.76/instrumentor/main.go"
    click OdigletSidecar "https://github.com/clouddetail/odigos/blob/apo-v1.0.76/odiglet/cmd/main.go"
    click OpAMP "https://github.com/clouddetail/odigos/tree/apo-v1.0.76/opampserver/"
    click Autoscaler "https://github.com/clouddetail/odigos/blob/apo-v1.0.76/autoscaler/main.go"
    click Scheduler "https://github.com/clouddetail/odigos/blob/apo-v1.0.76/scheduler/main.go"
    click CollectorPods "https://github.com/clouddetail/odigos/blob/apo-v1.0.76/collector/odigosotelcol/main.go"
    click CRDs "https://github.com/clouddetail/odigos/tree/apo-v1.0.76/api/"

    classDef control fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef data fill:#90EE90,stroke:#000,stroke-width:1px
    classDef k8s fill:#E0FFFF,stroke:#000,stroke-width:1px
    classDef external fill:#FFFACD,stroke:#000,stroke-width:1px
    classDef frontend fill:#F0E68C,stroke:#000,stroke-width:1px
    classDef config fill:#FFE4C4,stroke:#000,stroke-width:1px
```
