Quick Start Guide

Get Telegen running in under 5 minutes with zero configuration.

Overview

Telegen is designed to work out-of-the-box. The only required configuration is your OpenTelemetry endpoint—everything else is automatically discovered.

# Minimal configuration - just the endpoint!
telegen:
  otlp:
    endpoint: "otel-collector:4317"

Prerequisites

System Requirements

Component Minimum Recommended
CPU 200m (0.2 cores) 1 core
Memory 256 MB 1 GB
Disk 100 MB 500 MB
Kernel 4.18+ 5.8+

Kernel Requirements

Telegen requires Linux with eBPF support:

  • Minimum: Linux 4.18 (basic eBPF)
  • Recommended: Linux 5.8+ (CO-RE, BTF)
  • Optimal: Linux 5.15+ (ring buffer, improved performance)

Verify your setup:

# Check kernel version
uname -r

# Check for BTF support (recommended)
ls /sys/kernel/btf/vmlinux

# Check BPF filesystem
mount | grep bpf

Installation Methods

Helm

helm install telegen oci://ghcr.io/mirastacklabs-ai/charts/telegen \
  --namespace telegen --create-namespace \
  --set otlp.endpoint="otel-collector.observability:4317"

kubectl

kubectl apply -f https://raw.githubusercontent.com/mirastacklabs-ai/telegen/main/deployments/kubernetes/rbac.yaml
kubectl apply -f https://raw.githubusercontent.com/mirastacklabs-ai/telegen/main/deployments/kubernetes/configmap.yaml
kubectl apply -f https://raw.githubusercontent.com/mirastacklabs-ai/telegen/main/deployments/kubernetes/daemonset.yaml

Linux

# Download latest release
VERSION=$(curl -s https://api.github.com/repos/mirastacklabs-ai/telegen/releases/latest | grep tag_name | cut -d '"' -f4)
VERSION=${VERSION#release/mark-v}  # Strip prefix

# Download and install
curl -LO "https://github.com/mirastacklabs-ai/telegen/releases/download/release/mark-v${VERSION}/telegen-linux-amd64.tar.gz"
tar xzf telegen-linux-amd64.tar.gz
sudo mv telegen-linux-amd64 /usr/local/bin/telegen
sudo chmod +x /usr/local/bin/telegen

# Create minimal config and run
sudo mkdir -p /etc/telegen
echo 'otlp:
  endpoint: "otel-collector:4317"' | sudo tee /etc/telegen/config.yaml
sudo telegen --config /etc/telegen/config.yaml

See Linux for systemd service setup.

Docker

docker run -d --name telegen \
  --privileged \
  --pid=host \
  --network=host \
  -v /sys:/sys:ro \
  -v /proc:/host/proc:ro \
  -v /sys/kernel/debug:/sys/kernel/debug \
  -v /sys/fs/bpf:/sys/fs/bpf \
  -e TELEGEN_ENDPOINT=otel-collector:4317 \
  ghcr.io/mirastacklabs-ai/telegen:latest

Verify Installation

Check Agent Status

# Kubernetes
kubectl get pods -n telegen -l app.kubernetes.io/name=telegen

# Linux
systemctl status telegen

# Docker
docker logs telegen

Check Health Endpoint

curl http://localhost:8080/healthz

Expected response:

{"status": "healthy", "version": "3.0.0"}

Check Metrics

curl http://localhost:19090/metrics | head -20

Targeted Instrumentation (Optional)

By default, Telegen instruments all processes. For targeted instrumentation, use port-based discovery:

otlp:
  endpoint: "otel-collector:4317"

discovery:
  instrument:
    # Only instrument services on these ports
    - open_ports: "8080-8089"
    - open_ports: "3000,5000"

See Auto Discovery for more options including Kubernetes-aware targeting.

What Gets Collected

Once running, Telegen automatically collects:

Signal Description Protocol
Metrics Host, container, application metrics OTLP/Prometheus
Traces Distributed traces (HTTP, gRPC, DB) OTLP
Logs System and container logs OTLP
Profiles CPU, memory, off-CPU profiles OTLP

Auto-Discovered Metadata

Telegen automatically enriches all signals with:

  • Cloud Provider: AWS, GCP, Azure, Alibaba, Oracle, DigitalOcean
  • Kubernetes: namespace, pod, deployment, node
  • Host: OS, architecture, kernel version
  • Process: language runtime, framework detection

Next Steps

Back to top ↑