Back to Documentation

Configuration Guide

Configure HyperObserve Agent to match your infrastructure and monitoring needs

Configuration File Locations

Linux:
/etc/hyperobserve/agent.yaml
Windows:
C:\ProgramData\HyperObserve\config\agent.yaml
Docker:
/etc/hyperobserve/agent.yaml

💡 Tip: The agent automatically creates a default configuration on first run. You only need to modify it for custom settings.

Basic Configuration

Here's a minimal configuration to get you started:

# HyperObserve Agent Configuration
# Unique agent identifier (auto-generated if not set)
agent_id: "${HOSTNAME}-${RANDOM}"

# Server configuration
server:
  # Primary endpoint (auto-routes to nearest region)
  endpoint: "https://ingest.hyperobserve.com/v1/data"
  
  # License key (optional - uses 7-day trial if not provided)
  license_key: "${HYPEROBSERVE_LICENSE_KEY}"
  
  # API key for authentication (optional for trial)
  api_key: "${HYPEROBSERVE_API_KEY}"

# Basic collectors (enabled by default)
collectors:
  # System metrics (CPU, memory, disk, network)
  system:
    enabled: true
    interval: "10s"
    
  # Process monitoring
  process:
    enabled: true
    interval: "30s"

Environment Variables

Use ${VAR_NAME} syntax to reference environment variables in your config

Auto-reload

Configuration changes are automatically detected and applied without restart

Server & Endpoint Configuration

Regional Endpoints with Failover

server:
  # Primary endpoint (auto-failover enabled)
  endpoint: "https://ingest.hyperobserve.com/v1/data"
  
  # Regional endpoints for automatic failover
  fallback_endpoints:
    - "https://ingest-us.hyperobserve.com/v1/data"  # US East
    - "https://ingest-eu.hyperobserve.com/v1/data"  # EU West
    - "https://ingest-ap.hyperobserve.com/v1/data"  # Asia Pacific
  
  # Connection settings
  timeout: "30s"
  retry_attempts: 3
  retry_delay: "5s"

Buffering Configuration

server:
  # Buffer configuration for reliability
  buffer:
    type: "hybrid"         # memory, disk, or hybrid
    memory_size: "100MB"   # In-memory buffer size
    disk_size: "1GB"       # Disk buffer for overflow
    disk_path: "/var/lib/hyperobserve/buffer"
    
  # Compression
  compression: "zstd"      # none, gzip, zstd
  
  # Batch settings
  batch:
    size: 1000            # Max events per batch
    timeout: "10s"        # Max time before sending

Custom Backend Configuration

Send data to your own HyperObserve server or other backends:

# Send to custom HyperObserve server
server:
  endpoint: "https://your-hyperobserve-server.com/v1/data"
  api_key: "your-custom-api-key"
  tls:
    ca_cert: "/path/to/ca.crt"
    verify_hostname: true

# Or export to multiple backends
exporters:
  prometheus:
    enabled: true
    port: 9090
    path: "/metrics"
    
  elasticsearch:
    enabled: true
    endpoints: ["https://es.example.com:9200"]
    index_prefix: "hyperobserve-"

Collectors Configuration

System Metrics Collector

collectors:
  system:
    enabled: true
    interval: "10s"
    metrics:
      - cpu          # CPU usage and stats
      - memory       # Memory usage
      - disk         # Disk I/O and usage
      - network      # Network interfaces
      - filesystem   # Filesystem usage
    
    # Advanced CPU metrics
    cpu:
      per_core: true
      collect_temps: true
      
    # Disk filtering
    disk:
      ignore_mountpoints: ["/dev", "/sys", "/proc"]
      ignore_fs_types: ["tmpfs", "devfs"]

eBPF Monitoring (Linux Only)

collectors:
  ebpf:
    enabled: true
    programs:
      # Network monitoring
      - name: network_events
        enabled: true
        sampling_rate: 0.1  # Sample 10% of events
        
      # File system operations
      - name: file_operations
        enabled: true
        paths: ["/var/log", "/etc"]
        
      # Process lifecycle
      - name: process_lifecycle
        enabled: true
        
      # System calls (advanced)
      - name: syscalls
        enabled: false     # High overhead
        filter: ["open", "read", "write"]

Database Monitoring

collectors:
  databases:
    # PostgreSQL monitoring
    postgresql:
      enabled: true
      instances:
        - name: "production"
          host: "localhost"
          port: 5432
          username: "monitoring"
          password: "${POSTGRES_PASSWORD}"
          databases: ["app_db", "analytics_db"]
          collect_query_stats: true
          
    # MySQL monitoring
    mysql:
      enabled: true
      instances:
        - host: "localhost"
          port: 3306
          username: "monitoring"
          password: "${MYSQL_PASSWORD}"
          collect_slow_queries: true
          slow_query_threshold: "1s"
          
    # Redis monitoring
    redis:
      enabled: true
      instances:
        - host: "localhost:6379"
          password: "${REDIS_PASSWORD}"

Log Collection

collectors:
  logs:
    enabled: true
    paths:
      # Application logs
      - path: "/var/log/app/*.log"
        type: "json"
        multiline:
          pattern: '^{'
          negate: true
          match: after
          
      # Nginx logs
      - path: "/var/log/nginx/access.log"
        type: "nginx"
        processors:
          - grok:
              patterns: ['%{COMBINEDAPACHELOG}']
              
      # System logs
      - path: "/var/log/syslog"
        type: "syslog"
        exclude_patterns: ["DEBUG", "TRACE"]
        
    # Log processing
    processors:
      - timestamp:
          field: "timestamp"
          layouts: ["2006-01-02T15:04:05Z07:00"]
      - drop_fields:
          fields: ["agent_id", "host_id"]

Security Configuration

TLS Configuration

transport:
  tls:
    enabled: true
    # Custom CA certificate
    ca_file: "/etc/hyperobserve/ca.crt"
    
    # Client certificates (mutual TLS)
    cert_file: "/etc/hyperobserve/client.crt"
    key_file: "/etc/hyperobserve/client.key"
    
    # Security settings
    min_version: "1.2"
    verify_hostname: true
    insecure_skip_verify: false

Data Privacy & Filtering

collectors:
  # Global filters for sensitive data
  filters:
    # Redact email addresses
    - type: "regex"
      pattern: '\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'
      replacement: "[EMAIL]"
      
    # Redact credit card numbers
    - type: "regex"
      pattern: '\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14})\b'
      replacement: "[CREDIT_CARD]"
      
    # Drop sensitive fields
    - type: "field"
      fields: ["password", "secret", "token", "api_key", "ssn"]
      action: "drop"
      
    # Hash PII fields
    - type: "field"
      fields: ["user_id", "email", "ip_address"]
      action: "hash"

Access Control

# Local API access control
api:
  enabled: true
  listen: "127.0.0.1:8080"  # Local only
  
  # Authentication for API
  auth:
    type: "token"
    tokens:
      - name: "monitoring"
        token: "${API_TOKEN}"
        permissions: ["read"]
      - name: "admin"
        token: "${ADMIN_TOKEN}"
        permissions: ["read", "write", "reload"]
        
  # CORS settings (if needed)
  cors:
    allowed_origins: ["https://dashboard.example.com"]
    allowed_methods: ["GET", "POST"]

Advanced Configuration

Performance Tuning

# Resource limits
agent:
  limits:
    cpu_percent: 10        # Max 10% CPU usage
    memory_mb: 512         # Max 512MB memory
    disk_io_mbps: 50       # Max 50MB/s disk I/O
    
  # Worker configuration
  workers:
    collectors: 4          # Parallel collectors
    processors: 2          # Processing threads
    
  # Queue sizes
  queues:
    metrics: 10000         # Metrics queue size
    logs: 50000           # Logs queue size
    traces: 5000          # Traces queue size

Feature Flags

# Enable/disable features
features:
  # Enable experimental features
  enable:
    - "experimental_gpu_monitoring"
    - "advanced_network_topology"
    - "container_insights"
    
  # Disable specific features
  disable:
    - "legacy_metrics_format"
    - "deprecated_api_v1"
    
  # Feature-specific config
  config:
    gpu_monitoring:
      nvidia_smi_path: "/usr/bin/nvidia-smi"
      collection_interval: "30s"

High Availability

# HA configuration for multiple agents
high_availability:
  enabled: true
  
  # Coordination backend
  coordinator:
    type: "etcd"           # etcd, consul, zookeeper
    endpoints:
      - "https://etcd-1:2379"
      - "https://etcd-2:2379"
      - "https://etcd-3:2379"
      
  # Leader election
  leader_election:
    enabled: true
    lease_duration: "15s"
    renew_deadline: "10s"
    
  # Deduplication
  deduplication:
    enabled: true
    window: "60s"
    method: "hash"         # hash, timestamp

Configuration Examples

Minimal Production Config
# Minimal production configuration
server:
  endpoint: "https://ingest.hyperobserve.com/v1/data"
  license_key: "${HYPEROBSERVE_LICENSE_KEY}"
  
collectors:
  system:
    enabled: true
    interval: "10s"
  
  process:
    enabled: true
    interval: "30s"
    
  ebpf:
    enabled: true
    
agent:
  log_level: "info"
Full-Stack Monitoring Config
# Comprehensive full-stack monitoring
server:
  endpoint: "https://ingest.hyperobserve.com/v1/data"
  license_key: "${HYPEROBSERVE_LICENSE_KEY}"
  buffer:
    type: "hybrid"
    memory_size: "200MB"
    disk_size: "2GB"
    
collectors:
  system:
    enabled: true
    interval: "10s"
    
  ebpf:
    enabled: true
    programs: ["network_events", "file_operations", "process_lifecycle"]
    
  databases:
    postgresql:
      enabled: true
      instances:
        - host: "pg-primary:5432"
          username: "monitoring"
          password: "${PG_MONITOR_PASS}"
          
    redis:
      enabled: true
      instances:
        - host: "redis-primary:6379"
          
  logs:
    enabled: true
    paths:
      - path: "/var/log/app/*.log"
        type: "json"
      - path: "/var/log/nginx/*.log"
        type: "nginx"
        
  kubernetes:
    enabled: true
    api_server: "https://kubernetes.default.svc"
    
transport:
  compression: "zstd"
  
agent:
  limits:
    cpu_percent: 15
    memory_mb: 1024
Security-Focused Config
# Security-hardened configuration
server:
  endpoint: "https://ingest.hyperobserve.com/v1/data"
  license_key: "${HYPEROBSERVE_LICENSE_KEY}"
  
transport:
  tls:
    enabled: true
    min_version: "1.3"
    ca_file: "/etc/hyperobserve/ca.crt"
    verify_hostname: true
    
collectors:
  filters:
    - type: "regex"
      pattern: '\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'
      replacement: "[REDACTED]"
    - type: "field"
      fields: ["password", "secret", "token", "key", "credential"]
      action: "drop"
      
  system:
    enabled: true
    
  ebpf:
    enabled: true
    programs:
      - name: "security_events"
        enabled: true
      - name: "file_integrity"
        enabled: true
        paths: ["/etc", "/usr/bin", "/usr/sbin"]
        
api:
  enabled: false  # Disable local API
  
agent:
  user: "hyperobserve"
  group: "hyperobserve"
  umask: "0077"

Configuration Management

Reloading Configuration

# Linux - Reload without restart
sudo kill -SIGHUP $(pidof hyperobserve-agent)
# Or
sudo systemctl reload hyperobserve-agent

# Windows - Requires restart
Restart-Service "HyperObserve Agent"

Validating Configuration

# Validate configuration file
hyperobserve-agent config validate -f /etc/hyperobserve/agent.yaml

# Test configuration (dry run)
hyperobserve-agent --config /etc/hyperobserve/agent.yaml --dry-run

Environment Variables

Common environment variables for configuration:

HYPEROBSERVE_LICENSE_KEY=your-license-key
HYPEROBSERVE_API_KEY=your-api-key
HYPEROBSERVE_LOG_LEVEL=debug
HYPEROBSERVE_CONFIG=/custom/path/config.yaml
HYPEROBSERVE_OFFLINE_MODE=true

Need Help?

If you need help with configuration:

Next Steps

Deployment Guide →Best Practices →Troubleshooting →