Environment Variables

Complete reference for Telegen environment variables.

Overview

Environment variables provide the highest-priority configuration method. They override all config file settings and are ideal for:

  • Container deployments
  • Secrets management
  • CI/CD pipelines
  • Per-environment overrides

Naming Convention

Environment variables follow this pattern:

TELEGEN_<SECTION>_<SUBSECTION>_<KEY>

Examples:

  • TELEGEN_OTLP_ENDPOINT → otlp.endpoint
  • TELEGEN_AGENT_PROFILING_ENABLED → agent.profiling.enabled

Core Variables

Variable Default Description
TELEGEN_MODE agent Operating mode: agent or collector
TELEGEN_SERVICE_NAME telegen Service name for telemetry
TELEGEN_INSTANCE_ID hostname Unique instance identifier
TELEGEN_LOG_LEVEL info Log level: debug, info, warn, error
TELEGEN_LOG_FORMAT json Log format: json or text
TELEGEN_CONFIG_FILE /etc/telegen/config.yaml Config file path

OTLP Export Variables

Variable Default Description
TELEGEN_OTLP_ENDPOINT - Required. OTLP endpoint (e.g., otel-collector:4317)
TELEGEN_OTLP_PROTOCOL grpc Protocol: grpc or http
TELEGEN_OTLP_COMPRESSION gzip Compression: gzip or none
TELEGEN_OTLP_TIMEOUT 10s Connection timeout
TELEGEN_OTLP_INSECURE false Skip TLS verification
TELEGEN_OTLP_HEADERS - Headers as key=value,key2=value2

TLS Variables

Variable Default Description
TELEGEN_OTLP_TLS_ENABLED false Enable TLS
TELEGEN_OTLP_TLS_CA_FILE - CA certificate path
TELEGEN_OTLP_TLS_CERT_FILE - Client certificate path
TELEGEN_OTLP_TLS_KEY_FILE - Client key path
TELEGEN_OTLP_TLS_INSECURE_SKIP_VERIFY false Skip certificate verification

Per-Signal Variables

Variable Default Description
TELEGEN_OTLP_TRACES_ENABLED true Enable trace export
TELEGEN_OTLP_TRACES_ENDPOINT - Override traces endpoint
TELEGEN_OTLP_TRACES_SAMPLE_RATE 1.0 Trace sampling rate (0.0-1.0)
TELEGEN_OTLP_METRICS_ENABLED true Enable metrics export
TELEGEN_OTLP_METRICS_ENDPOINT - Override metrics endpoint
TELEGEN_OTLP_LOGS_ENABLED true Enable logs export
TELEGEN_OTLP_LOGS_ENDPOINT - Override logs endpoint
TELEGEN_OTLP_PROFILES_ENABLED true Enable profiles export
TELEGEN_OTLP_PROFILES_ENDPOINT - Override profiles endpoint

Agent Variables

eBPF Configuration

Variable Default Description
TELEGEN_AGENT_EBPF_ENABLED true Enable eBPF
TELEGEN_AGENT_EBPF_RINGBUF_SIZE 16777216 Ring buffer size (bytes)
TELEGEN_AGENT_EBPF_PERF_BUFFER_SIZE 8192 Per-CPU perf buffer size

Network Tracing

Variable Default Description
TELEGEN_AGENT_EBPF_NETWORK_ENABLED true Enable network tracing
TELEGEN_AGENT_EBPF_NETWORK_HTTP true Trace HTTP
TELEGEN_AGENT_EBPF_NETWORK_GRPC true Trace gRPC
TELEGEN_AGENT_EBPF_NETWORK_DNS true Trace DNS
TELEGEN_AGENT_EBPF_NETWORK_TCP_METRICS true Collect TCP metrics

Discovery

Variable Default Description
OTEL_EBPF_DISCOVERY_POLL_INTERVAL 5s Process discovery poll interval
OTEL_EBPF_EXCLUDE_OTEL_INSTRUMENTED_SERVICES true Skip OTel-instrumented services
OTEL_EBPF_MIN_PROCESS_AGE 5s Min process age before discovery
OTEL_EBPF_SKIP_GO_SPECIFIC_TRACERS false Use generic tracers only
OTEL_EBPF_BPF_PID_FILTER_OFF false Disable BPF PID filtering (debug)
OTEL_EBPF_DEFAULT_OTLP_GRPC_PORT 4317 Port for OTel-instrumented detection

Port-Based Discovery Variables

Variable Default Description
OTEL_EBPF_INSTRUMENT_PORTS - Ports to instrument (e.g., 8080,8000-8999)
OTEL_EBPF_INSTRUMENT_COMMAND - Glob pattern for executable path

Examples:

# Instrument only ports 8080-8089
export OTEL_EBPF_INSTRUMENT_PORTS="8080-8089"

# Instrument Java processes on port 8080
export OTEL_EBPF_INSTRUMENT_PORTS="8080"
export OTEL_EBPF_INSTRUMENT_COMMAND="*java*"

# Instrument common web ports
export OTEL_EBPF_INSTRUMENT_PORTS="80,443,3000,5000,8080-8089"

Metadata Discovery Variables

Variable Default Description
TELEGEN_AGENT_DISCOVERY_ENABLED true Enable metadata discovery
TELEGEN_AGENT_DISCOVERY_INTERVAL 30s Discovery interval
TELEGEN_AGENT_DISCOVERY_DETECT_CLOUD true Detect cloud provider
TELEGEN_AGENT_DISCOVERY_DETECT_KUBERNETES true Detect Kubernetes
TELEGEN_AGENT_DISCOVERY_DETECT_RUNTIMES true Detect application runtimes

Profiling

Variable Default Description
TELEGEN_AGENT_PROFILING_ENABLED false Enable profiling
TELEGEN_AGENT_PROFILING_SAMPLE_RATE 99 Sample rate (Hz)
TELEGEN_AGENT_PROFILING_CPU true CPU profiling
TELEGEN_AGENT_PROFILING_OFF_CPU true Off-CPU profiling
TELEGEN_AGENT_PROFILING_MEMORY true Memory profiling
TELEGEN_AGENT_PROFILING_DURATION 10s Profile duration
TELEGEN_AGENT_PROFILING_UPLOAD_INTERVAL 60s Upload interval

Security

Variable Default Description
TELEGEN_AGENT_SECURITY_ENABLED false Enable security monitoring
TELEGEN_AGENT_SECURITY_SYSCALL_AUDIT_ENABLED true Syscall auditing
TELEGEN_AGENT_SECURITY_FILE_INTEGRITY_ENABLED true File integrity monitoring
TELEGEN_AGENT_SECURITY_CONTAINER_ESCAPE_ENABLED true Container escape detection

GPU

Variable Default Description
TELEGEN_AGENT_GPU_ENABLED true Enable GPU monitoring
TELEGEN_AGENT_GPU_NVIDIA true NVIDIA GPU support
TELEGEN_AGENT_GPU_POLL_INTERVAL 10s GPU polling interval

Collector Variables

SNMP

Variable Default Description
TELEGEN_COLLECTOR_SNMP_ENABLED false Enable SNMP collection
TELEGEN_COLLECTOR_SNMP_POLL_INTERVAL 60s Polling interval
TELEGEN_COLLECTOR_SNMP_TIMEOUT 10s SNMP timeout
TELEGEN_COLLECTOR_SNMP_RETRIES 3 Retry count

SNMP Trap Receiver

Variable Default Description
TELEGEN_COLLECTOR_SNMP_TRAP_RECEIVER_ENABLED false Enable trap receiver
TELEGEN_COLLECTOR_SNMP_TRAP_RECEIVER_LISTEN :162 Listen address

Cloud Variables

AWS

Variable Default Description
TELEGEN_CLOUD_AWS_ENABLED true Enable AWS detection
TELEGEN_CLOUD_AWS_TIMEOUT 200ms Metadata timeout
TELEGEN_CLOUD_AWS_REFRESH_INTERVAL 15m Refresh interval
TELEGEN_CLOUD_AWS_COLLECT_TAGS false Collect EC2 tags

GCP

Variable Default Description
TELEGEN_CLOUD_GCP_ENABLED true Enable GCP detection
TELEGEN_CLOUD_GCP_TIMEOUT 200ms Metadata timeout
TELEGEN_CLOUD_GCP_REFRESH_INTERVAL 15m Refresh interval

Azure

Variable Default Description
TELEGEN_CLOUD_AZURE_ENABLED true Enable Azure detection
TELEGEN_CLOUD_AZURE_TIMEOUT 200ms Metadata timeout
TELEGEN_CLOUD_AZURE_REFRESH_INTERVAL 15m Refresh interval

Self-Telemetry Variables

The self-telemetry endpoint serves health probes (/healthz, /readyz) and Prometheus metrics (/metrics).

Variable Default Description
TELEGEN_SELF_TELEMETRY_LISTEN :19090 HTTP listen address for health probes and metrics
TELEGEN_SELF_TELEMETRY_PROMETHEUS_NAMESPACE telegen Prometheus metrics namespace prefix

Queue Variables

Variable Default Description
TELEGEN_QUEUES_TRACES_MEM_LIMIT 256Mi Trace queue memory limit
TELEGEN_QUEUES_TRACES_MAX_AGE 6h Max trace age
TELEGEN_QUEUES_TRACES_BATCH_SIZE 512 Trace batch size
TELEGEN_QUEUES_METRICS_MEM_LIMIT 128Mi Metrics queue memory limit
TELEGEN_QUEUES_METRICS_MAX_AGE 5m Max metrics age
TELEGEN_QUEUES_METRICS_BATCH_SIZE 1000 Metrics batch size
TELEGEN_QUEUES_LOGS_MEM_LIMIT 256Mi Logs queue memory limit
TELEGEN_QUEUES_LOGS_MAX_AGE 24h Max logs age
TELEGEN_QUEUES_LOGS_BATCH_SIZE 1000 Logs batch size

Backoff Variables

Variable Default Description
TELEGEN_BACKOFF_INITIAL 500ms Initial backoff
TELEGEN_BACKOFF_MAX 30s Maximum backoff
TELEGEN_BACKOFF_MULTIPLIER 2.0 Backoff multiplier
TELEGEN_BACKOFF_JITTER 0.2 Jitter factor
TELEGEN_BACKOFF_MAX_RETRIES 5 Max retry attempts

Usage Examples

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_OTLP_ENDPOINT=otel-collector:4317 \
  -e TELEGEN_AGENT_PROFILING_ENABLED=true \
  -e TELEGEN_AGENT_SECURITY_ENABLED=true \
  ghcr.io/mirastacklabs-ai/telegen:latest

Kubernetes ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: telegen-config
data:
  TELEGEN_OTLP_ENDPOINT: "otel-collector.monitoring:4317"
  TELEGEN_AGENT_PROFILING_ENABLED: "true"
  TELEGEN_AGENT_SECURITY_ENABLED: "true"
  TELEGEN_LOG_LEVEL: "info"

Kubernetes Secret

apiVersion: v1
kind: Secret
metadata:
  name: telegen-secrets
type: Opaque
stringData:
  TELEGEN_OTLP_HEADERS: "Authorization=Bearer your-token"

Shell Script

#!/bin/bash
export TELEGEN_OTLP_ENDPOINT="otel-collector:4317"
export TELEGEN_AGENT_PROFILING_ENABLED=true
export TELEGEN_AGENT_SECURITY_ENABLED=true
export TELEGEN_LOG_LEVEL=debug

telegen

Precedence

Configuration values are resolved in this order (highest to lowest):

  1. Environment variables - Always win
  2. Config file - Merged with defaults
  3. Built-in defaults - Fallback values

Example:

# config.yaml
otlp:
  endpoint: "from-config:4317"

# Environment
export TELEGEN_OTLP_ENDPOINT="from-env:4317"

Result: otlp.endpoint = from-env:4317

Secret Substitution

Config files support environment variable substitution using ${VAR} syntax:

otlp:
  endpoint: "${OTEL_ENDPOINT}"
  headers:
    Authorization: "Bearer ${OTEL_TOKEN}"

collector:
  snmp:
    targets:
      - address: "10.0.1.1:161"
        security:
          auth_password: "${SNMP_AUTH_PASSWORD}"
          priv_password: "${SNMP_PRIV_PASSWORD}"

Next Steps

Back to top ↑