Skip to content

5. Developer API

Jump to bottom
Vincenzo Reina edited this page Apr 21, 2025 · 9 revisions

Developer API

ServerPulse provides a comprehensive API that allows other plugins to interact with and extend its functionality. This guide covers how to integrate with ServerPulse and use its features in your plugins.

Adding ServerPulse as Dependency

Plugin Dependency

Add ServerPulse to your plugin.yml:

depend: [ServerPulse]  # Hard dependency
# OR
softdepend: [ServerPulse]  # Soft dependency

Maven Dependency

<dependency>
    <groupId>it.renvins</groupId>
    <artifactId>serverpulse-api</artifactId>
    <version>0.1.5-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>

Gradle Dependency

dependencies {
    compileOnly("it.renvins:serverpulse-api:0.1.5-SNAPSHOT")
}

Getting Started

Accessing the API

import it.renvins.serverpulse.api.ServerPulseAPI;
import it.renvins.serverpulse.api.ServerPulseProvider;

public class YourPlugin extends JavaPlugin {
    
    @Override
    public void onEnable() {
        // Check if ServerPulse is available
        if (getServer().getPluginManager().getPlugin("ServerPulse") != null) {
            try {
                ServerPulseAPI api = ServerPulseProvider.get();
                // Use the API here
            } catch (IllegalStateException e) {
                getLogger().warning("ServerPulse API is not available!");
            }
        }
    }
}

Core API Components

Database Service

The IDatabaseService interface provides access to InfluxDB operations:

IDatabaseService dbService = api.getDatabaseService();

// Check connection status
boolean isConnected = dbService.isConnected();

// Get InfluxDB client for custom queries
InfluxDBClient client = dbService.getClient();
WriteApi writeApi = dbService.getWriteApi();

// Send custom data point
Point point = Point.measurement("custom_stats")
    .addTag("plugin", "your_plugin")
    .addField("value", 42)
    .time(Instant.now(), WritePrecision.NS);
writeApi.writePoint(point);

Metrics Service

The IMetricsService interface handles metric collection:

IMetricsService metricsService = api.getMetricsService();

// Trigger metrics collection manually
metricsService.collectAndSendMetrics();

Disk Metrics

The IDiskRetriever interface provides disk space information:

IDiskRetriever diskRetriever = api.getDiskRetriever();

// Get disk space metrics
long totalSpace = diskRetriever.getTotalSpace();
long usableSpace = diskRetriever.getUsableSpace();

Player Ping

The IPingRetriever interface provides player ping statistics:

IPingRetriever pingRetriever = api.getPingRetriever();

// Get ping statistics
int minPing = pingRetriever.getMinPing();
int maxPing = pingRetriever.getMaxPing();
int avgPing = pingRetriever.getAveragePing();

Example: Custom Metrics Plugin

Here's a complete example of a plugin that tracks custom metrics:

public class CustomMetricsPlugin extends JavaPlugin {
    
    private ServerPulseAPI api;
    
    @Override
    public void onEnable() {
        if (!setupServerPulse()) {
            getLogger().severe("Failed to setup ServerPulse integration!");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }
        
        startMetricsTask();
    }
    
    private boolean setupServerPulse() {
        Plugin serverPulse = getServer().getPluginManager().getPlugin("ServerPulse");
        if (serverPulse == null) {
            return false;
        }
        
        try {
            api = ServerPulseProvider.get();
            return true;
        } catch (IllegalStateException e) {
            return false;
        }
    }
    
    private void startMetricsTask() {
        // Run every 5 minutes (6000 ticks)
        getServer().getScheduler().runTaskTimerAsynchronously(this, () -> {
            if (!api.getDatabaseService().isConnected()) {
                return;
            }
            
            // Create and send custom metrics
            Point point = Point.measurement("custom_plugin_stats")
                .addTag("server", "your_server")
                .addTag("plugin", "CustomMetrics")
                .addField("active_features", countActiveFeatures())
                .addField("custom_count", getCustomCount())
                .time(Instant.now(), WritePrecision.NS);
                
            api.getDatabaseService().getWriteApi().writePoint(point);
        }, 0L, 6000L);
    }
    
    private int countActiveFeatures() {
        // Your implementation
        return 42;
    }
    
    private int getCustomCount() {
        // Your implementation
        return 123;
    }
}

Best Practices

  1. Error Handling

    • Always check if ServerPulse is available
    • Handle API exceptions gracefully
    • Verify connection status before sending metrics

  2. Performance

    • Send metrics asynchronously
    • Batch metrics when possible
    • Use appropriate collection intervals

  3. Data Organization

    • Use consistent measurement names
    • Add relevant tags for filtering
    • Structure fields logically

Related Pages

Clone this wiki locally