Skip to content

2. Configuration

Jump to bottom
Vincenzo Reina edited this page May 15, 2025 · 6 revisions

ServerPulse Configuration Guide

This guide covers all configuration options available in ServerPulse across all supported platforms: Bukkit/Paper, Velocity, and Fabric.

Configuration Files Locations

Each platform stores its configuration in a different location:

  • Bukkit/Paper: plugins/ServerPulse/config.yml
  • Velocity: plugins/serverpulse/config.yml
  • Fabric: config/serverpulse/config.yml

Common Configuration Structure

All platforms share the same core configuration structure with minor variations in the messages section:

metrics:
  interval: 5          # Collection interval in seconds
  influxdb:
    url: http://localhost:8086  # InfluxDB API URL
    org: my-org               # Organization name
    bucket: metrics_db        # Bucket for storing metrics
    token: my-token          # API token (replace this!)
    table: minecraft_stats   # Measurement name in InfluxDB
  tags:
    server: "server-id"      # Server identifier (change this for each server)
messages:
  # Message configurations vary by platform (see below)

Platform-Specific Configurations

Bukkit/Paper Configuration

Default configuration with explanations:

metrics:
  interval: 5
  influxdb:
    url: http://localhost:8086
    org: my-org
    bucket: metrics_db
    token: my-token
    table: minecraft_stats
  tags:
    server: "bed1"      # Change to a unique identifier for your server
messages:
  noPerms: "&7[&bServer&7Pulse] &7You don't have &bpermission &7to use this &bcommand&7."
  reloadConfig: "&7[&bServer&7Pulse] &7Configuration &breloaded&7."
  reloadConfigError: "&7[&bServer&7Pulse] &7Error &breloading &7configuration..."
  noArgs: "&7[&bServer&7Pulse] &7You need to specify a &bcommand&7: &breload&7, &bstatus&7."
  playerOnly: "&7[&bServer&7Pulse] &7This command can only be used by &bplayers&7."
  noCommand: "&7[&bServer&7Pulse] &7This command is not &bavailable&7."
  reloadConfigUsage: "&7[&bServer&7Pulse] &7Usage: &b/serverpulse reload&7."
  statusConfigUsage: "&7[&bServer&7Pulse] &7Usage: &b/serverpulse status&7."
  statusConnected: "&7[&bServer&7Pulse] &7Connected to &bInfluxDB&7."
  statusNotConnected: "&7[&bServer&7Pulse] &7Not connected to &bInfluxDB&7."

Velocity Configuration

metrics:
  interval: 5
  influxdb:
    url: http://localhost:8086
    org: my-org
    bucket: metrics_db
    token: my-token
    table: minecraft_stats
  tags:
    server: "velocity1"   # Change to a unique identifier for your proxy
messages:
  usage: "&7[&bServer&7Pulse] &7Please use &b/serverpulsevelocity [status|reload]&7."
  reloadConfig: "&7[&bServer&7Pulse] &7Configuration &breloaded&7."
  reloadConfigError: "&7[&bServer&7Pulse] &7Error &breloading &7configuration..."
  statusConnected: "&7[&bServer&7Pulse] &7Connected to &bInfluxDB&7."
  statusNotConnected: "&7[&bServer&7Pulse] &7Not connected to &bInfluxDB&7."

Fabric Configuration

metrics:
  interval: 5
  influxdb:
    url: http://localhost:8086
    org: my-org
    bucket: metrics_db
    token: my-token
    table: minecraft_stats
  tags:
    server: "fabric1"    # Change to a unique identifier for your Fabric server
messages:
  usage: "&7[&bServer&7Pulse] &7Please use &b/serverpulse [status|reload]&7."
  reloadConfig: "&7[&bServer&7Pulse] &7Configuration &breloaded&7."
  reloadConfigError: "&7[&bServer&7Pulse] &7Error &breloading &7configuration..."
  statusConnected: "&7[&bServer&7Pulse] &7Connected to &bInfluxDB&7."
  statusNotConnected: "&7[&bServer&7Pulse] &7Not connected to &bInfluxDB&7."

Metrics Settings

Main Options

  • metrics.interval: How often metrics are collected and sent
    • Value in seconds
    • Minimum: 1 second
    • Recommended: 5-15 seconds
    • Higher values reduce server impact but provide less granular data

InfluxDB Connection

Required Settings

  • metrics.influxdb.url: URL of your InfluxDB instance

    • Format: http://hostname:port
    • Default port is 8086
    • Use localhost if running on same machine

  • metrics.influxdb.org: Organization name in InfluxDB

    • Must match the organization created during InfluxDB setup
    • Default: my-org

  • metrics.influxdb.bucket: Bucket name for metrics storage

    • Must exist in InfluxDB
    • Default: metrics_db

  • metrics.influxdb.token: API token for authentication

    • Generate this in InfluxDB UI
    • Requires read and write permissions
    • Never share this token publicly

  • metrics.influxdb.table: Measurement name

    • Groups all metrics under this name
    • Default: minecraft_stats
    • Change only if you know what you're doing

Tags System

Server Tag

The metrics.tags.server setting is crucial for identifying metrics from different servers. Use a unique identifier for each server:

  • For Bukkit/Paper servers:

    metrics:
  tags:
    server: "survival-1"

  • For Velocity proxies:

    metrics:
  tags:
    server: "velocity1"

  • For Fabric servers:

    metrics:
  tags:
    server: "fabric1"

Custom Tags

You can add additional tags to better organize your metrics:

metrics:
  tags:
    server: "survival-1"
    region: "eu-west"    # Geographic location
    type: "survival"     # Server type
    network: "main"      # Network identifier

These tags can be used in Grafana to filter and group metrics.

Messages Configuration

All platforms support customizing plugin messages. Messages support color codes using the & symbol and will be automatically reloaded when using the reload command for your platform.

Platform-Specific Considerations

Bukkit/Paper Specific Settings

The Bukkit/Paper implementation automatically detects if you're running Paper or a Paper fork and will use the native TPS API if available. If you're running standard Bukkit/Spigot, it will use its own TPS monitoring implementation.

Velocity Specific Settings

The Velocity implementation focuses on proxy-specific metrics and doesn't include TPS or world-related metrics since these aren't applicable to a proxy server. Instead, it provides detailed ping statistics for players connected through the proxy.

Fabric Specific Settings

The Fabric implementation includes a custom TPS monitoring system similar to the Bukkit implementation. It uses Fabric API events to track server performance and monitor world data.

Multi-Server Setup

When monitoring different types of servers in the same infrastructure:

  1. Use different server tag values for each server/proxy/mod
  2. Use a consistent naming scheme (e.g., "proxy1", "survival1", "creative1", "fabric1")
  3. Configure all servers to use the same InfluxDB instance
  4. In Grafana, you can create dashboard variables to switch between different servers

Verifying Configuration

After changing your configuration, you can verify it works correctly:

  • For Bukkit/Paper: Use /serverpulse status command
  • For Velocity: Use /serverpulsevelocity status command (or /spv status shorthand)
  • For Fabric: Use /serverpulse status command

All commands will show if the plugin/mod is successfully connected to InfluxDB.

Sample Multi-Server Config

Here's an example of how to configure ServerPulse in a network with multiple server types:

Main Velocity Proxy

metrics:
  tags:
    server: "proxy-main"
    type: "proxy"
    network: "survival-network"

Bukkit Survival Server

metrics:
  tags:
    server: "survival-1"
    type: "survival"
    network: "survival-network"

Fabric Creative Server

metrics:
  tags:
    server: "creative-fabric"
    type: "creative"
    network: "survival-network"

This structure allows you to filter metrics in Grafana by server type, specific server, or network.

Clone this wiki locally