Skip to content

telemetryflow/telemetryflow-agent

BranchesTags

Repository files navigation

TelemetryFlow Logo

TelemetryFlow Agent (OTEL Agent)

Version License Go Version OTEL SDK OpenTelemetry

Enterprise-grade telemetry collection agent built on OpenTelemetry Go SDK v1.39.0. Provides comprehensive system monitoring with metrics collection, heartbeat monitoring, and OTLP telemetry export for the TelemetryFlow Platform.

This agent works as the client-side counterpart to the TelemetryFlow Backend Agent Module (NestJS), providing:

  • Agent registration & lifecycle management
  • Heartbeat & health monitoring
  • System metrics collection
  • OTLP telemetry export

TelemetryFlow Ecosystem

TFO-Agent is fully aligned with the TelemetryFlow ecosystem, sharing the same OpenTelemetry SDK version:

graph LR
    subgraph "TelemetryFlow Ecosystem v1.1.1"
        subgraph "Instrumentation"
            SDK[TFO-Go-SDK<br/>OTEL SDK v1.39.0]
        end

        subgraph "Collection"
            AGENT[TFO-Agent<br/>OTEL SDK v1.39.0]
        end

        subgraph "Processing"
            COLLECTOR[TFO-Collector<br/>OTEL v0.142.0]
        end
    end

    APP[Application] --> SDK
    SDK -->|OTLP| AGENT
    HOST[Host Metrics] --> AGENT
    AGENT -->|OTLP gRPC/HTTP| COLLECTOR
    COLLECTOR --> BACKEND[TelemetryFlow<br/>Platform]

    style SDK fill:#81C784,stroke:#388E3C
    style AGENT fill:#64B5F6,stroke:#1976D2
    style COLLECTOR fill:#FFB74D,stroke:#F57C00
Loading
Component Version OTEL Base Description
TFO-Agent v1.1.1 SDK v1.39.0 Telemetry collection agent
TFO-Go-SDK v1.1.1 SDK v1.39.0 Go instrumentation SDK
TFO-Collector v1.1.1 Collector v0.142.0 Central telemetry collector

Features

OpenTelemetry Core

  • OpenTelemetry SDK v1.39.0: Built on standard OTEL Go SDK (aligned with TFO-Go-SDK)
  • OTLP Export: OpenTelemetry Protocol for metrics, logs, and traces
  • Multi-Signal Support: Metrics, logs, and traces collection

Agent Lifecycle (Backend Integration)

  • Agent Registration: Auto-register with TelemetryFlow backend
  • Heartbeat Monitoring: Regular health checks to backend
  • Health Status Sync: Report agent health and system info
  • Activation/Deactivation: Remote agent control from backend

System Monitoring

  • System Metrics Collection: CPU, memory, disk, and network metrics
  • Process Monitoring: Track running processes
  • Resource Detection: Auto-detect host, OS, and container info

Reliability

  • Disk-Backed Buffer: Resilient retry buffer for offline scenarios
  • Auto-Reconnection: Automatic retry with exponential backoff
  • Graceful Shutdown: Signal handling (SIGINT, SIGTERM, SIGHUP)

Platform

  • Cross-Platform: Linux, macOS, and Windows support
  • LEGO Building Blocks: Modular architecture for easy extensibility

Quick Start

From Source

# Clone the repository
git clone https://github.com/telemetryflow/telemetryflow-agent.git
cd telemetryflow-agent

# Build
make build

# Run
./build/tfo-agent --help

Docker

Using Docker Compose (Recommended)

# Copy environment template
cp .env.example .env

# Edit .env with your configuration
vim .env

# Build and start
docker-compose up -d --build

# View logs
docker-compose logs -f tfo-agent

# Stop
docker-compose down

Using Docker Directly

# Build image
docker build \
  --build-arg VERSION=1.1.1 \
  --build-arg GIT_COMMIT=$(git rev-parse --short HEAD) \
  --build-arg GIT_BRANCH=$(git rev-parse --abbrev-ref HEAD) \
  --build-arg BUILD_TIME=$(date -u '+%Y-%m-%dT%H:%M:%SZ') \
  -t telemetryflow/telemetryflow-agent:1.1.1 .

# Run container
docker run -d --name tfo-agent \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 8888:8888 \
  -p 13133:13133 \
  -v /path/to/config.yaml:/etc/tfo-agent/tfo-agent.yaml:ro \
  -v /var/lib/tfo-agent:/var/lib/tfo-agent \
  telemetryflow/telemetryflow-agent:1.1.1

Configuration

Create configuration file at /etc/tfo-agent/tfo-agent.yaml:

# TelemetryFlow Platform Configuration (v1.1.1+)
telemetryflow:
  api_key_id: "${TELEMETRYFLOW_API_KEY_ID}"
  api_key_secret: "${TELEMETRYFLOW_API_KEY_SECRET}"
  endpoint: "${TELEMETRYFLOW_ENDPOINT:-localhost:4317}"
  protocol: grpc  # grpc or http
  tls:
    enabled: true
    skip_verify: false
  retry:
    enabled: true
    max_attempts: 3
    initial_interval: 1s
    max_interval: 30s

agent:
  name: "TelemetryFlow Agent"
  hostname: ""  # Auto-detected if empty
  tags:
    environment: production

heartbeat:
  interval: 60s
  timeout: 10s

collector:
  system:
    enabled: true
    interval: 15s
    cpu: true
    memory: true
    disk: true
    network: true

exporter:
  otlp:
    enabled: true
    batch_size: 100
    flush_interval: 10s
    compression: gzip

buffer:
  enabled: true
  path: "/var/lib/tfo-agent/buffer"
  max_size_mb: 100

Environment Variables

# TelemetryFlow Platform (v1.1.1+)
export TELEMETRYFLOW_ENDPOINT="localhost:4317"
export TELEMETRYFLOW_API_KEY_ID="tfk_your_key_id"
export TELEMETRYFLOW_API_KEY_SECRET="tfs_your_key_secret"
export TELEMETRYFLOW_ENVIRONMENT="production"

# Agent Configuration
export TELEMETRYFLOW_AGENT_ID="your-agent-id"
export TELEMETRYFLOW_AGENT_NAME="my-agent"

# Logging
export TELEMETRYFLOW_LOG_LEVEL="info"

Usage

# Start agent
tfo-agent start

# Start with custom config
tfo-agent start --config /path/to/config.yaml

# Validate configuration
tfo-agent config validate

# Show version
tfo-agent version

Project Structure

tfo-agent/
├── cmd/tfo-agent/         # CLI entry point
├── internal/
│   ├── agent/             # Core agent lifecycle
│   ├── buffer/            # Disk-backed retry buffer
│   ├── collector/         # Metric collectors
│   │   └── system/        # System metrics collector
│   ├── config/            # Configuration management
│   ├── exporter/          # OTLP data exporters
│   └── version/           # Version and banner info
├── pkg/                   # LEGO Building Blocks
│   ├── api/               # HTTP API client
│   ├── banner/            # Startup banner
│   ├── config/            # Config loader utilities
│   └── plugin/            # Plugin registry system
├── configs/               # Configuration templates
├── scripts/               # Build/install scripts
├── build/                 # Build output
├── Makefile
├── Dockerfile             # Docker build
├── docker-compose.yml     # Docker Compose
├── .env.example           # Environment template
└── README.md

LEGO Building Blocks

The pkg/ directory contains reusable building blocks:

Block Description
pkg/banner ASCII art startup banner
pkg/config Flexible configuration loader
pkg/plugin Plugin registry for extensibility
pkg/api HTTP client for backend communication

Adding Custom Plugins

import "github.com/telemetryflow/telemetryflow/telemetryflow-agent/pkg/plugin"

// Register a custom collector
plugin.Register("my-collector", func() plugin.Plugin {
    return &MyCustomCollector{}
})

// Use the plugin
p, _ := plugin.Get("my-collector")
p.Init(config)
p.Start()

Collected Metrics

Metric Type Description
system.cpu.usage gauge CPU usage percentage
system.cpu.cores gauge Number of CPU cores
system.memory.total gauge Total memory (bytes)
system.memory.used gauge Used memory (bytes)
system.memory.usage gauge Memory usage percentage
system.disk.total gauge Total disk space (bytes)
system.disk.used gauge Used disk space (bytes)
system.disk.usage gauge Disk usage percentage
system.network.bytes_sent counter Total bytes sent
system.network.bytes_recv counter Total bytes received

Development

Prerequisites

  • Go 1.24 or later
  • Make

Build Commands

# Show all commands
make help

# Build Commands
make                # Build agent (default)
make build          # Build agent for current platform
make build-all      # Build agent for all platforms
make build-linux    # Build for Linux (amd64 and arm64)
make build-darwin   # Build for macOS (amd64 and arm64)

# Development Commands
make run            # Build and run agent
make dev            # Run with go run (faster for development)
make test           # Run tests
make test-coverage  # Run tests with coverage report
make lint           # Run linter
make fmt            # Format code
make vet            # Run go vet

# Dependencies
make deps           # Download dependencies
make deps-update    # Update dependencies
make tidy           # Tidy go modules

# Other Commands
make clean          # Clean build artifacts
make install        # Install binary to /usr/local/bin
make uninstall      # Uninstall binary
make docker-build   # Build Docker image
make docker-push    # Push Docker image
make version        # Show version information

Systemd Service

# /etc/systemd/system/tfo-agent.service
[Unit]
Description=TelemetryFlow Agent - CEOP
After=network.target

[Service]
Type=simple
User=telemetryflow
ExecStart=/usr/local/bin/tfo-agent start --config /etc/tfo-agent/tfo-agent.yaml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable tfo-agent
sudo systemctl start tfo-agent

Documentation

Document Description
README Documentation overview
ARCHITECTURE System architecture with Mermaid diagrams
INSTALLATION Installation guide for all platforms
CONFIGURATION Configuration options and examples
COMMANDS CLI commands reference
DEVELOPMENT Development guide and coding standards
TROUBLESHOOTING Troubleshooting guide and common issues
GITHUB-WORKFLOWS CI/CD workflows documentation
CHANGELOG Version history and changes

License

Apache License 2.0 - See LICENSE

Links

Copyright (c) 2024-2026 DevOpsCorner Indonesia. All rights reserved.

About

TelemetryFlow Agent (OTEL Agent)

www.telemetryflow.id

Topics

otel opentelemetry opentelemetry-go otel-agent devopscorner opentelemetry-agent telemetryflow

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 3

TelemetryFlow Agent v1.1.1 Latest
Dec 29, 2025
+ 2 releases

Packages

No packages published

Contributors 2

  •  
  •  

Languages