Core Concepts

Understanding Telegen’s architecture and terminology.

Deployment Modes

Telegen operates in two distinct modes:

Agent Mode

Agent mode is for local host/container observability. Deploy directly on each node you want to monitor.

graph LR
    A[Host/Container] --> B[Telegen Agent]
    B --> C[eBPF Instrumentation]
    B --> D[Process Discovery]
    B --> E[Log Collection]
    C --> F[OTLP Export]
    D --> F
    E --> F
    F --> G[OTel Collector]

Capabilities:

  • eBPF-based kernel instrumentation
  • Process discovery and runtime detection
  • Continuous profiling (CPU, memory, mutex)
  • GPU/CUDA monitoring
  • Local log collection
  • Container and Kubernetes enrichment

Deployment: DaemonSet (Kubernetes), systemd service (bare metal)

Collector Mode

Collector mode is for remote device monitoring. Deploy on a separate node to collect telemetry from remote systems.

graph LR
    A[Network Devices] -->|SNMP| B[Telegen Collector]
    C[Storage Arrays] -->|REST API| B
    D[Cloud APIs] -->|HTTPS| B
    B --> E[OTLP Export]
    E --> F[OTel Collector]

Capabilities:

  • SNMP polling and trap receiver (v1/v2c/v3)
  • Storage array metrics (Dell, HPE, Pure, NetApp)
  • Cloud/infrastructure API polling
  • Database metrics receivers

Deployment: Deployment/StatefulSet (Kubernetes), systemd service (bare metal)

Signal Types

Telegen produces four signal types, all in OpenTelemetry format:

Signal Description Use Case
Metrics Time-series numerical data Dashboards, alerting
Traces Distributed request flows Latency analysis, debugging
Logs Structured event records Debugging, auditing
Profiles CPU/memory stack samples Performance optimization

Signal Correlation

All signals are automatically correlated:

  • Logs include trace_id and span_id
  • Metrics include exemplars linking to trace samples
  • Profiles are correlated with active spans

Auto-Discovery

Telegen automatically detects and enriches telemetry with:

Cloud Detection

Provider Detection Method
AWS IMDSv2 (169.254.169.254)
GCP Metadata server
Azure IMDS
Alibaba Metadata service
Oracle IMDS
DigitalOcean Metadata service
OpenStack Keystone + env vars
VMware Hypervisor detection

Runtime Detection

Runtime Detection Method
Go Binary symbols, runtime headers
Java JVM process, JFR
Python Interpreter process
Node.js V8 engine detection
.NET CoreCLR detection

Database Detection

Database Detection Method
PostgreSQL Port 5432, protocol detection
MySQL Port 3306, protocol detection
Redis Port 6379, RESP protocol
MongoDB Port 27017, wire protocol
Kafka Port 9092, broker detection

eBPF Programs

Telegen uses eBPF (Extended Berkeley Packet Filter) for kernel-level instrumentation:

graph TB
    subgraph Kernel
        A[eBPF Programs]
        B[kprobes/uprobes]
        C[Tracepoints]
        D[XDP]
    end
    subgraph "User Space"
        E[Telegen Agent]
        F[Ring Buffer]
    end
    A --> B
    A --> C
    A --> D
    B --> F
    C --> F
    D --> F
    F --> E

eBPF Program Types Used

Type Purpose
kprobe Kernel function tracing
uprobe User-space function tracing
tracepoint Kernel tracepoint hooks
perf_event CPU profiling
XDP High-performance packet processing
tc Traffic control for egress

Resource Attributes

Telegen follows OpenTelemetry semantic conventions for resource attributes:

# Automatically added to all signals
resource:
  service.name: "my-service"
  service.namespace: "production"
  host.name: "node-1"
  host.arch: "amd64"
  os.type: "linux"
  cloud.provider: "aws"
  cloud.region: "us-east-1"
  k8s.namespace.name: "default"
  k8s.pod.name: "my-pod-abc123"
  k8s.node.name: "node-1"

Next Steps

Back to top ↑