roseeast/PawnMetrics

---

Pawn Metrics lets Pawn gamemodes expose server, gameplay, economy, admin, and anti-cheat metrics through a lightweight HTTP endpoint. It is designed for server owners who want modern monitoring with Prometheus, Grafana, uptime dashboards, or simple HTTP scrapers.

Overview

Features

Release Files

Prebuilt release packages are available in release/.

Package layout:

pawn-metrics-v0.2.0/
  plugins/
    pawn_metrics.so
    pawn_metrics.dll
  components/
    pawn_metrics.so
    pawn_metrics.dll
  pawno/include/
    pawn_metrics.inc
  examples/
    example.pwn
    pawn_metrics.cfg
  README.md
  LICENSE
  CHANGELOG.md

Compatibility

Pawn Metrics does not hook RakNet, patch memory, or depend on internal SA-MP addresses. It only registers Pawn natives and runs a small HTTP listener for metrics scraping.

Installation

1. Install Files

For SA-MP (Legacy Plugin)

Copy the files from plugins/ into your server:

plugins/pawn_metrics.so        -> Linux server plugins folder
plugins/pawn_metrics.dll       -> Windows server plugins folder
pawno/include/pawn_metrics.inc -> Pawn compiler include folder

For open.mp (Native Component - Recommended)

Copy the files from components/ into your server:

components/pawn_metrics.so     -> Linux server components folder
components/pawn_metrics.dll    -> Windows server components folder
pawno/include/pawn_metrics.inc -> Pawn compiler include folder

For Qawno or custom build systems, place pawn_metrics.inc in the include path used by your compiler.

2. Load The Plugin / Component

For SA-MP server.cfg:

plugins pawn_metrics

On some older Linux setups:

plugins pawn_metrics.so

For open.mp config.json (Native Component Mode - Recommended):

{
  "components": [
    "pawn_metrics"
  ]
}

For open.mp config.json (Legacy Plugin Mode):

{
  "pawn": {
    "legacy_plugins": ["pawn_metrics"]
  }
}

3. Include In Pawn

#include <pawn_metrics>

Quick Start

#include <a_samp>
#include <pawn_metrics>

public OnGameModeInit()
{
    Metrics_SetAuthToken("change-this-token");
    Metrics_StartEx("127.0.0.1", 9100);
    Metrics_UpdateServerInfo();
    Metrics_SetInt("samp_players_online", 0);
    Metrics_SetInt("samp_connects_total", 0);
    Metrics_SetLabeledInt("samp_reports_open", "type=\"player\"", 0);

    SetTimer("Metrics_Update", 5000, true);
    return 1;
}

public OnPlayerConnect(playerid)
{
    Metrics_Inc("samp_connects_total");
    Metrics_SetPlayersOnline();
    Metrics_ObserveHistogram("samp_player_connect_seconds", 0.05);
    return 1;
}

forward Metrics_Update();
public Metrics_Update()
{
    Metrics_UpdateServerInfo();
    Metrics_SetPlayersOnline();
    Metrics_ObserveSummaryLabeled("samp_tick_work_seconds", "source=\"metrics\"", 0.001);
    return 1;
}

Then open:

http://127.0.0.1:9100/metrics?token=change-this-token

Native API

Config File

Example scriptfiles/pawn_metrics.cfg:

bind=127.0.0.1
port=9100
auth_token=change-this-token

Usage:

public OnGameModeInit()
{
    if (!Metrics_StartFromConfig("scriptfiles/pawn_metrics.cfg"))
    {
        print("[pawn-metrics] failed to start from config");
    }

    return 1;
}

Authentication

If auth_token is empty, the endpoint is public. If a token is configured, requests must use one of these forms:

Authorization: Bearer change-this-token
http://127.0.0.1:9100/metrics?token=change-this-token

For production servers, bind to 127.0.0.1 or firewall the metrics port unless Prometheus runs on a trusted remote host.

Stock Helpers

The include provides convenience stocks:

Metrics_UpdateServerInfo();
Metrics_SetPlayersOnline();

Metrics_SetPlayersOnline loops over GetMaxPlayers() and writes:

samp_players_online

Metric Naming

Metric names must be Prometheus-safe:

[a-zA-Z_:][a-zA-Z0-9_:]*

Good examples:

samp_players_online
samp_connects_total
samp_disconnects_total
samp_commands_total
samp_reports_total
samp_anticheat_flags_total
samp_money_created_total
samp_money_removed_total
samp_mysql_queries_total
samp_loaded_vehicles
samp_loaded_houses

Invalid names are ignored by the plugin.

Prometheus

Example prometheus.yml:

scrape_configs:
  - job_name: samp
    scrape_interval: 5s
    static_configs:
      - targets: ["127.0.0.1:9100"]

Example output:

# HELP pawn_metrics_info Pawn metrics plugin scrape info
# TYPE pawn_metrics_info gauge
pawn_metrics_info 1
# TYPE samp_connects_total gauge
samp_connects_total 18
# TYPE samp_players_online gauge
samp_players_online 7

Grafana Ideas

Build From Source

This repository uses CMake (version 3.20+).

Requirements

Linux

cmake -B build -S .
cmake --build build

Output:

• build/plugins/pawn_metrics.so (Legacy SA-MP plugin)
• build/components/pawn_metrics.so (Native open.mp component)

Windows (Cross-compile with MinGW)

cmake -B build-win -S . -DCMAKE_SYSTEM_NAME=Windows -DCMAKE_CXX_COMPILER=i686-w64-mingw32-g++
cmake --build build-win

Output:

• build-win/plugins/pawn_metrics.dll (Legacy SA-MP plugin)
• build-win/components/pawn_metrics.dll (Native open.mp component)

The default Windows target is 32-bit because classic SA-MP Windows servers are 32-bit.

GitHub Actions

The workflow in .github/workflows/build.yml fetches the SA-MP plugin SDK and builds release artifacts for Linux and Windows.

Troubleshooting

Security Notes

The metrics endpoint supports a simple bearer/query token. Bind or firewall it so only Prometheus, Grafana, or trusted monitoring hosts can access it.

Do not expose sensitive data such as passwords, auth tokens, private IPs, or player personal information as metric names or values.

License

Pawn Metrics is released under the MIT License.