Back to Documentation
setup
v1.0

Configuration Guide

Complete configuration reference for Nodewarden agent and monitoring options

Last updated: September 6, 2025
7 min read

Configuration Guide

This guide covers all configuration options for Nodewarden agent and monitoring setup.

Agent Configuration

The Nodewarden agent uses a simple configuration file located at /etc/nodewarden/nodewarden.conf.

Basic Configuration

yaml
# /etc/nodewarden/nodewarden.conf

# Required: Your API key from the Nodewarden dashboard
api_key: "nw_sk_your_api_key_here"

# Required: Unique identifier for this host
host_id: "your-host-id"

# API endpoint (default: https://api.nodewarden.com)
api_url: "https://api.nodewarden.com"

# Agent version (auto-detected, don't modify)
version: "1.0.0"

Data Collection Settings

Configure how often the agent collects and sends metrics:

yaml
# Metrics collection interval (seconds)
collection_interval: 60

# Batch size for sending metrics
batch_size: 100

# Maximum retry attempts for failed requests
max_retries: 3

# Timeout for API requests (seconds)
request_timeout: 30

System Metrics Configuration

Control which system metrics are collected:

yaml
# System metrics collection
metrics:
  # CPU metrics
  cpu:
    enabled: true
    include_per_core: false  # Set to true for per-core CPU stats
    
  # Memory metrics
  memory:
    enabled: true
    include_swap: true
    
  # Disk metrics
  disk:
    enabled: true
    include_partitions: ["*"]  # List specific partitions or use "*" for all
    exclude_partitions: ["/snap/*", "/dev/loop*"]  # Exclude patterns
    
  # Network metrics
  network:
    enabled: true
    include_interfaces: ["*"]  # List specific interfaces or use "*" for all
    exclude_interfaces: ["lo", "docker*"]  # Exclude patterns
    
  # Load average
  load:
    enabled: true
    
  # Uptime
  uptime:
    enabled: true

Process Monitoring

Monitor specific processes running on your system:

yaml
# Process monitoring configuration
processes:
  # Monitor nginx process
  - name: "nginx"
    enabled: true
    track_memory: true
    track_cpu: true
    track_connections: true  # For network services
    
  # Monitor MySQL/MariaDB
  - name: "mysql"
    enabled: true
    track_memory: true
    track_cpu: true
    
  # Monitor custom application
  - name: "my-app"
    enabled: true
    command_pattern: "java -jar my-app.jar"  # Optional: match by command
    track_memory: true
    track_cpu: true
    track_threads: true

Service Discovery

Automatically discover and monitor services:

yaml
# Service discovery settings
discovery:
  # Auto-discover running services
  enabled: true
  
  # Discovery interval (seconds)
  interval: 300
  
  # Service patterns to auto-monitor
  patterns:
    - "nginx*"
    - "apache*"
    - "mysql*"
    - "postgres*"
    - "redis*"
    - "mongodb*"
    
  # Exclude patterns
  exclude:
    - "*test*"
    - "*dev*"

Custom Metrics

Send custom metrics from your applications:

yaml
# Custom metrics endpoint
custom_metrics:
  # Enable local metrics endpoint
  enabled: true
  
  # Local port for metrics submission
  port: 9100
  
  # Authentication token for local submissions
  token: "local-secret-token"
  
  # Accepted metric types
  types:
    - "counter"
    - "gauge"
    - "histogram"
    - "summary"

Logging Configuration

Control agent logging behavior:

yaml
# Logging settings
logging:
  # Log level: debug, info, warn, error
  level: "info"
  
  # Log file location
  file: "/var/log/nodewarden/agent.log"
  
  # Log rotation
  max_size: "100MB"
  max_files: 5
  max_age: 30  # days
  
  # Also log to stdout
  console: false

Security Settings

Configure security options:

yaml
# Security configuration
security:
  # Verify SSL certificates
  verify_ssl: true
  
  # Custom CA certificate (if using self-signed certs)
  ca_cert: "/path/to/ca-cert.pem"
  
  # Client certificate authentication
  client_cert: "/path/to/client-cert.pem"
  client_key: "/path/to/client-key.pem"
  
  # Proxy settings
  proxy:
    enabled: false
    http_proxy: "http://proxy.company.com:8080"
    https_proxy: "http://proxy.company.com:8080"
    no_proxy: "localhost,127.0.0.1,*.internal.com"

Environment Variables

You can override configuration using environment variables:

bash
# Override API key
export NODEWARDEN_API_KEY="nw_sk_your_api_key"

# Override API URL
export NODEWARDEN_API_URL="https://api.nodewarden.com"

# Override host ID
export NODEWARDEN_HOST_ID="prod-web-01"

# Set log level
export NODEWARDEN_LOG_LEVEL="debug"

Platform-Specific Configuration

Linux Systems

yaml
# Linux-specific settings
linux:
  # Monitor systemd services
  systemd:
    enabled: true
    monitor_failed: true
    
  # Monitor cron jobs
  cron:
    enabled: true
    track_failures: true

Windows Systems

yaml
# Windows-specific settings
windows:
  # Monitor Windows services
  services:
    enabled: true
    include: ["*"]
    exclude: ["Windows*", "Microsoft*"]
    
  # Performance counters
  performance_counters:
    enabled: true
    counters:
      - "\\Processor(_Total)\\% Processor Time"
      - "\\Memory\\Available MBytes"
      - "\\PhysicalDisk(_Total)\\% Disk Time"

Container Environments

yaml
# Container detection and monitoring
containers:
  # Auto-detect container environment
  detect: true
  
  # Docker settings
  docker:
    enabled: true
    socket: "/var/run/docker.sock"
    monitor_containers: true
    collect_logs: false
    
  # Kubernetes settings
  kubernetes:
    enabled: true
    in_cluster: true  # Set to true when running inside K8s
    namespace: "default"

Advanced Configuration

High Availability Setup

For critical environments, configure redundancy:

yaml
# High availability settings
ha:
  # Enable HA mode
  enabled: true
  
  # Backup API endpoints
  backup_endpoints:
    - "https://api-backup1.nodewarden.com"
    - "https://api-backup2.nodewarden.com"
    
  # Local metric buffer (for network outages)
  buffer:
    enabled: true
    size: "1GB"
    location: "/var/lib/nodewarden/buffer"

Performance Tuning

Optimize for large-scale deployments:

yaml
# Performance settings
performance:
  # Number of worker threads
  workers: 4
  
  # Metric collection parallelism
  parallel_collectors: true
  
  # Memory limits
  max_memory: "512MB"
  
  # CPU limits (percentage)
  max_cpu: 10
  
  # Nice value (Linux)
  nice: 19

Integration Settings

Configure third-party integrations:

yaml
# Integrations
integrations:
  # Prometheus compatibility
  prometheus:
    enabled: true
    port: 9090
    path: "/metrics"
    
  # StatsD compatibility
  statsd:
    enabled: true
    port: 8125
    
  # OpenTelemetry
  opentelemetry:
    enabled: false
    endpoint: "localhost:4317"
    protocol: "grpc"

Configuration Validation

Validate your configuration:

bash
# Check configuration syntax
nodewarden config validate

# Test configuration (dry run)
nodewarden config test

# Show effective configuration
nodewarden config show

Common Configuration Examples

Web Server Monitoring

yaml
# Optimized for web servers
api_key: "nw_sk_your_key"
host_id: "prod-web-01"

metrics:
  cpu:
    enabled: true
  memory:
    enabled: true
  network:
    enabled: true
    include_interfaces: ["eth0", "eth1"]

processes:
  - name: "nginx"
    enabled: true
    track_connections: true
  - name: "php-fpm"
    enabled: true
    track_memory: true

Database Server Monitoring

yaml
# Optimized for database servers
api_key: "nw_sk_your_key"
host_id: "prod-db-01"

metrics:
  cpu:
    enabled: true
    include_per_core: true
  memory:
    enabled: true
  disk:
    enabled: true
    include_partitions: ["/var/lib/mysql"]

processes:
  - name: "mysqld"
    enabled: true
    track_memory: true
    track_cpu: true
    track_threads: true

Container Host Monitoring

yaml
# Optimized for container hosts
api_key: "nw_sk_your_key"
host_id: "prod-docker-01"

containers:
  docker:
    enabled: true
    monitor_containers: true

metrics:
  cpu:
    enabled: true
  memory:
    enabled: true
  disk:
    enabled: true
    exclude_partitions: ["/var/lib/docker/overlay2/*"]

Troubleshooting Configuration

Debug Mode

Enable debug logging to troubleshoot issues:

yaml
logging:
  level: "debug"
  console: true

Common Issues

  1. Agent not starting: Check configuration syntax with nodewarden config validate
  2. Metrics not appearing: Verify API key and host ID are correct
  3. High CPU usage: Reduce collection frequency or disable unused metrics
  4. Network errors: Check proxy settings and SSL configuration

Configuration Best Practices

  1. Start simple: Begin with basic configuration and add features as needed
  2. Use environment variables: For sensitive data like API keys
  3. Monitor agent performance: Ensure monitoring doesn't impact system performance
  4. Regular updates: Keep agent updated for new configuration options
  5. Document changes: Track configuration modifications in version control

Need Help?

  • Check our troubleshooting guide
  • Contact support at support@nodewarden.com
  • Join our community forum for configuration tips

Was this page helpful?

Help us improve our documentation

    Configuration Guide | Nodewarden Documentation