README
¶
Telegen
A unified telemetry agent for collecting and exporting metrics, traces, logs, and Java profiling data using OpenTelemetry and Prometheus protocols.
One agent, many signals. All signal types are config-driven pipelines:
- Metrics: Host metrics with Remote Write export
- Traces: eBPF-based distributed tracing with OTLP export
- Logs: File tailing with OTLP export
- JFR: Java Flight Recorder profiling converted to JSON for OTel ingestion
- Grafana Dashboard: RED + agent health with exemplar-ready panels
- Helm Chart: DaemonSet + Service + ServiceMonitor + RBAC
Quick Start
go mod tidy
make build
./bin/telegen --config ./api/config.example.yaml
# optional: make bpf # build CO-RE BPF .o files for ringbuf path
Deploy with Helm
helm install telegen ./deployments/helm
Docker
make docker
Grafana
Import dashboards/telegen-red-grafana.json into Grafana. Panels include queue pressure, exporter failures, latency p90,
and request-rate placeholders. To enable exemplars (trace links), ensure Prometheus has exemplar storage enabled and your
OTLP traces include span IDs that your backend can reference.
Configuration
All signal pipelines are enabled/disabled via config. See api/config.example.yaml for the full reference.
JFR Pipeline
The JFR pipeline watches for Java Flight Recorder files and converts them to JSON for ingestion by OTel Collector's filelog receiver.
pipelines:
jfr:
enabled: true
input_dirs: # Directories to watch for .jfr files
- "/var/log/jfr"
recursive: true # Scan subdirectories (default: true)
output_dir: "/var/log/jfr-json" # Where to write converted JSON files
poll_interval: "5s" # How often to scan for new files
workers: 2 # Number of parallel conversion workers
Architecture
Java App (JFR) → /var/log/jfr/*.jfr → Telegen JFR Pipeline → /var/log/jfr-json/*.json → OTel Collector → Backend
Java Profiling (eBPF Continuous Profiling)
Telegen includes production-ready eBPF continuous profiling with symbol resolution for Java applications. Native functions, kernel symbols, and JIT-compiled Java methods are all resolved to human-readable function names.
Quick Start - IBM OpenJ9
# Add to your Java application deployment
env:
- name: OPENJ9_JAVA_OPTIONS
value: "-Xjit:perfTool" # Enables perf map generation
Quick Start - Oracle/OpenJDK HotSpot
# Requires perf-map-agent (see docs/java-profiling-quick-start.md)
env:
- name: JAVA_TOOL_OPTIONS
value: "-XX:+PreserveFramePointer -agentpath:/opt/perf-map/libperfmap.so"
Validate Configuration
./scripts/validate-java-profiling.sh <namespace> <deployment-name>
Documentation
- Quick Start: docs/java-profiling-quick-start.md - TL;DR configuration and validation
- OpenJ9 Deep Dive: docs/java-openj9-profiling.md - Comprehensive OpenJ9 guide with troubleshooting
- OpenShift Deployment: deployments/openshift/java-openj9-profiling.yaml - Production-ready manifests
What Gets Resolved?
✅ Native/C++ functions (libjvm.so, glibc, etc.) - Always works
✅ Kernel functions (syscalls, page faults, etc.) - Always works
✅ Go functions (pclntab-based) - Always works for Go binaries
✅ Java JIT methods - Requires perf map configuration (see above)
Without JIT perf maps, Java methods show as [unresolved] 0x... addresses.
AWS Metadata (optional)
When enabled, Telegen enriches traces, logs, and metrics with AWS resource attributes and labels using IMDSv2.
Config example:
cloud:
aws:
enabled: true
timeout: "200ms" # per IMDS request
refresh_interval: "15m" # metadata cache refresh
collect_tags: false # opt-in; requires IMDS instance tags enabled
tag_allowlist: [] # e.g., ["app_", "env"]
Directories
¶
| Path | Synopsis |
|---|---|
|
database
Package database contains eBPF programs for database query tracing.
|
Package database contains eBPF programs for database query tracing. |
|
profiler
Placeholder for Go build - profiler BPF programs
|
Placeholder for Go build - profiler BPF programs |
|
cmd
|
|
|
telegen
command
|
|
|
configs
|
|
|
offsets
command
|
|
|
offsets/http2
command
|
|
|
internal
|
|
|
agent
Package agent provides the core Telegen agent implementation.
|
Package agent provides the core Telegen agent implementation. |
|
agent/memory
Package memory provides memory budget management for the Telegen agent.
|
Package memory provides memory budget management for the Telegen agent. |
|
aiml
Package aiml provides AI/ML observability for Telegen.
|
Package aiml provides AI/ML observability for Telegen. |
|
aiml/framework
Package framework provides ML framework profiling integration.
|
Package framework provides ML framework profiling integration. |
|
aiml/llm
Package llm provides LLM token metrics collection for AI observability.
|
Package llm provides LLM token metrics collection for AI observability. |
|
aiml/nvidia
Package nvidia provides NVIDIA GPU metrics collection via NVML.
|
Package nvidia provides NVIDIA GPU metrics collection via NVML. |
|
appolly/core
Package appolly provides public access to eBPF application observability as a library
|
Package appolly provides public access to eBPF application observability as a library |
|
cloud/unified
Package unified provides a unified cloud abstraction layer for detecting and collecting metrics from public clouds (AWS, GCP, Azure), private clouds (OpenStack, VMware, Nutanix), and on-premises infrastructure.
|
Package unified provides a unified cloud abstraction layer for detecting and collecting metrics from public clouds (AWS, GCP, Azure), private clouds (OpenStack, VMware, Nutanix), and on-premises infrastructure. |
|
correlation
Package correlation provides signal correlation for OpenTelemetry.
|
Package correlation provides signal correlation for OpenTelemetry. |
|
database
Package database provides eBPF-based database and message queue tracing.
|
Package database provides eBPF-based database and message queue tracing. |
|
database/postgres
Package postgres provides PostgreSQL-specific database tracing utilities.
|
Package postgres provides PostgreSQL-specific database tracing utilities. |
|
database/redis
Package redis provides Redis-specific database tracing utilities.
|
Package redis provides Redis-specific database tracing utilities. |
|
discover/exec
Package exec provides the utilities to analyze the executable code
|
Package exec provides the utilities to analyze the executable code |
|
ebpf
Package ebpf provides eBPF program lifecycle management.
|
Package ebpf provides eBPF program lifecycle management. |
|
ebpf/tcmanager
line below avoids linter errors on Mac
|
line below avoids linter errors on Mac |
|
export/profiles
Package profiles provides OTLP profile export functionality.
|
Package profiles provides OTLP profile export functionality. |
|
exporters
Package exporters provides unified signal export capabilities.
|
Package exporters provides unified signal export capabilities. |
|
exporters/otelexport
Package otelexport provides OTel Collector-friendly export functionality.
|
Package otelexport provides OTel Collector-friendly export functionality. |
|
exporters/otlp
Package otlp provides unified OTLP export for traces, metrics, logs, and profiles.
|
Package otlp provides unified OTLP export for traces, metrics, logs, and profiles. |
|
exporters/otlp/logs
Package logs provides OTLP log export functionality for profile events.
|
Package logs provides OTLP log export functionality for profile events. |
|
exporters/otlp/profiles
Package profiles provides OTLP profile data model and conversion.
|
Package profiles provides OTLP profile data model and conversion. |
|
exporters/remotewrite
Package remotewrite provides Prometheus Remote Write export that is compatible with the OTel Collector's prometheusremotewritereceiver.
|
Package remotewrite provides Prometheus Remote Write export that is compatible with the OTel Collector's prometheusremotewritereceiver. |
|
goexec
Package goexec provides the utilities to analyze the executable code
|
Package goexec provides the utilities to analyze the executable code |
|
helpers/container
Package container provides helper tools to inspect container information
|
Package container provides helper tools to inspect container information |
|
jfr/converter
Package converter provides JFR to JSON conversion functionality.
|
Package converter provides JFR to JSON conversion functionality. |
|
jfr/watcher
Package watcher provides file watching functionality for JFR files.
|
Package watcher provides file watching functionality for JFR files. |
|
kube/kubecache/meta/cni
Package cni provides utilities for working with Container Network Interface (CNI) configurations.
|
Package cni provides utilities for working with Container Network Interface (CNI) configurations. |
|
kubemetrics
Package kubemetrics provides unified Kubernetes metrics collection combining kube-state-metrics equivalent (kubestate) and cAdvisor equivalent (cadvisor).
|
Package kubemetrics provides unified Kubernetes metrics collection combining kube-state-metrics equivalent (kubestate) and cAdvisor equivalent (cadvisor). |
|
logs/filetailer
Package filetailer provides file-based log collection with container runtime format parsing and Kubernetes metadata extraction.
|
Package filetailer provides file-based log collection with container runtime format parsing and Kubernetes metadata extraction. |
|
logs/parsers
Package parsers provides log parsing capabilities for container runtime formats, Kubernetes metadata extraction, and application-specific log parsing (e.g., Spring Boot).
|
Package parsers provides log parsing capabilities for container runtime formats, Kubernetes metadata extraction, and application-specific log parsing (e.g., Spring Boot). |
|
netinfra
Package netinfra provides network infrastructure observability integrations for Arista CloudVision and Cisco ACI platforms.
|
Package netinfra provides network infrastructure observability integrations for Arista CloudVision and Cisco ACI platforms. |
|
netinfra/arista
Package arista provides Arista CloudVision integration for network observability.
|
Package arista provides Arista CloudVision integration for network observability. |
|
netinfra/cisco
Package cisco provides Cisco ACI integration for network observability.
|
Package cisco provides Cisco ACI integration for network observability. |
|
netinfra/types
Package types provides shared types for network infrastructure observability.
|
Package types provides shared types for network infrastructure observability. |
|
network
Package network provides unified network observability for Telegen v2.0.
|
Package network provides unified network observability for Telegen v2.0. |
|
network/grpc
Package grpc provides gRPC call tracing functionality.
|
Package grpc provides gRPC call tracing functionality. |
|
network/multicast
Package multicast provides broadcast and multicast traffic tracking.
|
Package multicast provides broadcast and multicast traffic tracking. |
|
network/servicemesh
Package servicemesh provides integration with service mesh control planes.
|
Package servicemesh provides integration with service mesh control planes. |
|
network/topology
Package topology provides network topology tracking and visualization.
|
Package topology provides network topology tracking and visualization. |
|
nodeexporter
Package nodeexporter provides Prometheus node_exporter compatible system metrics collection for telegen.
|
Package nodeexporter provides Prometheus node_exporter compatible system metrics collection for telegen. |
|
nodeexporter/collector
Package collector provides the core collector framework for node_exporter compatible metrics collection.
|
Package collector provides the core collector framework for node_exporter compatible metrics collection. |
|
obiconfig
Package config contains some configuration options that need to be in a public package to let Alloy accessing them
|
Package config contains some configuration options that need to be in a public package to let Alloy accessing them |
|
pipeline
Package pipeline provides the signal processing pipeline for Telegen.
|
Package pipeline provides the signal processing pipeline for Telegen. |
|
profiler
Package profiler provides eBPF-based profiling with multiple export formats.
|
Package profiler provides eBPF-based profiling with multiple export formats. |
|
profiler/perfmap
Package perfmap provides perf-map-agent integration for Java JIT symbol resolution.
|
Package perfmap provides perf-map-agent integration for Java JIT symbol resolution. |
|
rdns/ebpf/xdp
Package xdp provides DNS message parsing functionality for the XDP-based DNS response tracker.
|
Package xdp provides DNS message parsing functionality for the XDP-based DNS response tracker. |
|
ringbuf
Package ringbuf provides some type aliases to prevent testing/compilation errors in non-linux environments due to the use of Cilium's ringbuf package, which is only available on Linux.
|
Package ringbuf provides some type aliases to prevent testing/compilation errors in non-linux environments due to the use of Cilium's ringbuf package, which is only available on Linux. |
|
security
Package security provides security observability features including syscall auditing, file integrity monitoring, and container escape detection.
|
Package security provides security observability features including syscall auditing, file integrity monitoring, and container escape detection. |
|
selftelemetry
Package selftelemetry provides self-monitoring metrics for the Telegen agent.
|
Package selftelemetry provides self-monitoring metrics for the Telegen agent. |
|
semconv
Package semconv provides OpenTelemetry semantic convention helpers for Telegen.
|
Package semconv provides OpenTelemetry semantic convention helpers for Telegen. |
|
sigdef
Package sigdef provides signal metadata definitions for Telegen telemetry.
|
Package sigdef provides signal metadata definitions for Telegen telemetry. |
|
snmp
Package snmp implements an SNMP receiver for integrating legacy infrastructure (network devices, storage systems, UPS, printers, HVAC, industrial equipment) into modern observability stacks.
|
Package snmp implements an SNMP receiver for integrating legacy infrastructure (network devices, storage systems, UPS, printers, HVAC, industrial equipment) into modern observability stacks. |
|
split
Package split provides an Iterator that allows for zero-copy string splitting.
|
Package split provides an Iterator that allows for zero-copy string splitting. |
|
storage
Package storage provides infrastructure storage metrics collection.
|
Package storage provides infrastructure storage metrics collection. |
|
storage/dell
Package dell provides collectors for Dell storage arrays.
|
Package dell provides collectors for Dell storage arrays. |
|
storage/hpe
Package hpe provides collectors for HPE storage arrays.
|
Package hpe provides collectors for HPE storage arrays. |
|
storage/netapp
Package netapp provides collectors for NetApp storage arrays.
|
Package netapp provides collectors for NetApp storage arrays. |
|
storage/pure
Package pure provides collectors for Pure Storage arrays.
|
Package pure provides collectors for Pure Storage arrays. |
|
storagedef
Package storagedef provides shared type definitions for storage adapters.
|
Package storagedef provides shared type definitions for storage adapters. |
|
tracers/cudatracer
Package cudatracer provides eBPF-based CUDA kernel and memory operation tracing.
|
Package cudatracer provides eBPF-based CUDA kernel and memory operation tracing. |
|
tracers/llmtracer
Package llmtracer provides eBPF-based LLM API request tracing.
|
Package llmtracer provides eBPF-based LLM API request tracing. |
|
transform
Package transform provides some intermediate nodes that might filter/process/transform the events
|
Package transform provides some intermediate nodes that might filter/process/transform the events |
|
validation
Package validation provides OpenTelemetry semantic convention validation.
|
Package validation provides OpenTelemetry semantic convention validation. |
|
pkg
|
|
|
export/attributes/names
Package attr contains definition of the attribute names of for the metrics, especially for the metrics whose reported attributes are selected in the attributes.select YAML option
|
Package attr contains definition of the attribute names of for the metrics, especially for the metrics whose reported attributes are selected in the attributes.select YAML option |
|
export/connector
Package connector provides tools for sharing the connection of diverse exporters (Prometheus, OTEL...) from different nodes
|
Package connector provides tools for sharing the connection of diverse exporters (Prometheus, OTEL...) from different nodes |
|
export/debug
Package debug provides some export nodes that are aimed basically at debugging/testing
|
Package debug provides some export nodes that are aimed basically at debugging/testing |
|
export/imetrics
Package imetrics supports recording and submission of internal metrics
|
Package imetrics supports recording and submission of internal metrics |
|
export/otel/metric/components/x
Package x contains support for OTel metric SDK experimental features.
|
Package x contains support for OTel metric SDK experimental features. |
|
export/otel/perapp
Package perapp is a placeholder for the future global and per-service support of different metrics/traces export options.
|
Package perapp is a placeholder for the future global and per-service support of different metrics/traces export options. |
|
pipe/msg
Package msg provides tools for message passing and queues between the different nodes of the Beyla pipelines.
|
Package msg provides tools for message passing and queues between the different nodes of the Beyla pipelines. |
|
pipe/swarm
Package swarm provides tools for the creation and coordination of the nodes that go inside the different Beyla pipelines
|
Package swarm provides tools for the creation and coordination of the nodes that go inside the different Beyla pipelines |
|
pipe/swarm/swarms
Package swarms provides helper functions for operating OBI swarms
|
Package swarms provides helper functions for operating OBI swarms |
Click to show internal directories.
Click to hide internal directories.