mirrors/crafty-documentation
1
0
Fork 0
mirror of https://gitlab.com/crafty-controller/crafty-documentation.git synced 2025-12-05 01:10:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'tweak/prometheus-metrics-doc' into 'main'

Browse Source 
Prometheus openmetrics doc

See merge request crafty-controller/crafty-documentation!18
This commit is contained in:
Iain Powrie
2025-11-24 17:05:14 +00:00
parent e66fc8409c 1dd1cc3d1f
commit 262bee0704
3 changed files with 256 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
docs/pages/developer-guide/api-reference/openapi-spec.yml
View File

@@ -29,6 +29,8 @@ tags:
description: User actions
- name: Crafty
description: Crafty management requests
- name: Metrics
description: Prometheus/OpenMetrics endpoints for monitoring Crafty and servers
components:
securitySchemes:
bearerAuth:
@@ -1962,3 +1964,123 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/StatusError"
/metrics:
get:
tags:
- Metrics
summary: Global Crafty metrics
description: |
Returns Crafty's global Prometheus/OpenMetrics registry.
Includes Python runtime metrics and Crafty instance metadata.
responses:
200:
description: Metrics output in OpenMetrics format.
content:
text/plain:
schema:
type: string
example: |
# HELP python_gc_objects_collected_total Objects collected during gc
# TYPE python_gc_objects_collected_total counter
python_gc_objects_collected_total{generation="0"} 10836.0
python_gc_objects_collected_total{generation="1"} 4676.0
python_gc_objects_collected_total{generation="2"} 99.0
# HELP python_gc_objects_uncollectable_total Uncollectable objects found during GC
# TYPE python_gc_objects_uncollectable_total counter
python_gc_objects_uncollectable_total{generation="0"} 0.0
python_gc_objects_uncollectable_total{generation="1"} 0.0
python_gc_objects_uncollectable_total{generation="2"} 0.0
# HELP python_gc_collections_total Number of times this generation was collected
# TYPE python_gc_collections_total counter
python_gc_collections_total{generation="0"} 167.0
python_gc_collections_total{generation="1"} 15.0
python_gc_collections_total{generation="2"} 1.0
# HELP python_info Python platform information
# TYPE python_info gauge
python_info{implementation="CPython",major="3",minor="12",patchlevel="9",version="3.12.9"} 1.0
# HELP Crafty_Controller_info Infos of this Crafty Instance
# TYPE Crafty_Controller_info gauge
Crafty_Controller_info{docker="False",version="4.6.2"} 1.0
403:
description: Authentication failed.
content:
application/json:
schema:
$ref: "#/components/schemas/StatusError"
/metrics/host:
get:
tags:
- Metrics
summary: Host system metrics
description: |
Returns host-level CPU and memory metrics from the machine running Crafty.
Output is Prometheus/OpenMetrics format.
responses:
200:
description: Host metrics in OpenMetrics format.
content:
text/plain:
schema:
type: string
example: |
# HELP CPU_Usage The CPU usage of the server
# TYPE CPU_Usage gauge
CPU_Usage 1.54
# HELP Mem_Usage The Memory usage of the server
# TYPE Mem_Usage gauge
Mem_Usage 63.8
400:
description: User lacks global access permissions.
content:
application/json:
schema:
$ref: "#/components/schemas/StatusError"
403:
description: Authentication failed.
content:
application/json:
schema:
$ref: "#/components/schemas/StatusError"
/metrics/servers/{serverID}:
get:
tags:
- Metrics
summary: Metrics for a specific managed server
description: |
Returns detailed Prometheus/OpenMetrics metrics for a Crafty-managed server,
including CPU, memory, version, and player information.
Requires that the authenticated user has access to the target server.
parameters:
- $ref: "#/components/parameters/ServerID"
responses:
200:
description: Server metrics in OpenMetrics format.
content:
text/plain:
schema:
type: string
example: |
# HELP CPU_Usage The CPU usage of the server
# TYPE CPU_Usage gauge
CPU_Usage{server_id="ef3fb2d1-a94c-4d9b-8c65-c4274be706cb"} 0.78
# HELP Mem_Usage The Memory usage of the server
# TYPE Mem_Usage gauge
Mem_Usage{server_id="ef3fb2d1-a94c-4d9b-8c65-c4274be706cb"} 4.0
# HELP Minecraft_Version_info The version of the minecraft of this server
# TYPE Minecraft_Version_info gauge
Minecraft_Version_info{server_id="ef3fb2d1-a94c-4d9b-8c65-c4274be706cb",version="Paper 1.21.10"} 1.0
# HELP online_players The number of players online for a server
# TYPE online_players gauge
online_players{server_id="ef3fb2d1-a94c-4d9b-8c65-c4274be706cb"} 0.0
400:
description: User does not have permission for this server.
content:
application/json:
schema:
$ref: "#/components/schemas/StatusError"
403:
description: Authentication failed.
content:
application/json:
schema:
$ref: "#/components/schemas/StatusError"

133
docs/pages/user-guide/open-metrics.md Normal file
View File

@@ -0,0 +1,133 @@
# Using Crafty OpenMetrics for Monitoring :simple-prometheus:
This document covers Crafty's Open Metrics implementation, which allows for comprehensive monitoring and scraping of Crafty Statistics by prometheus.
With this functionality, users can leverage platforms like Grafana to visualize and monitor host metrics, Crafty's operational stats, and individual server statistics.
## Available Metrics Endpoints
Crafty provides several endpoints for metrics collection, each serving a specific set of data:
- `/metrics` - Global Crafty metrics, including Python runtime stats and Crafty instance information.
- `/metrics/host` - Host machine metrics, including CPU and memory usage of the system Crafty is running on.
- `/metrics/servers/{serverID}` - Detailed metrics for an individual managed server.
The `{serverID}` value is the server’s UUID, not a numeric database index.
For a complete reference to all the data points available through these endpoints, as well as `curl` examples please consult the [Crafty API Documentation](../developer-guide/api-reference/v2.md).
## User Permissions and Access
Server administrators (SuperUsers) have unfettered access to all server statistics via the Open Metrics endpoints. Non-admin users must be assigned a specific role linked to a server to access its statistics.
## Prometheus Configuration
To integrate with Prometheus, you will need to configure Prometheus to scrape metrics from Crafty's endpoints.
!!! tip "API Token Preparation"
Remember, API tokens are sensitive and should be kept secure. Ensure that they are not exposed in configuration files or logs.
```bash
sudo mkdir -p /etc/prometheus/secrets
sudo chmod 700 /etc/prometheus/secrets
sudo sh -c 'echo "YOUR_JWT_TOKEN_HERE" > /etc/prometheus/secrets/crafty_token'
sudo chmod 600 /etc/prometheus/secrets/crafty_token
```
!!! example "Prometheus Configs :simple-prometheus:"
In your `prometheus.yml`, add the following jobs under the existing `scrape_configs:` section.
=== "Scrape global metrics: `/metrics`"
```yaml
- job_name: 'crafty-global'
scheme: https
metrics_path: /metrics
scrape_interval: 5s
tls_config:
# For self-signed certs while testing – better to install a CA in production
insecure_skip_verify: true
authorization:
type: Bearer
# Prometheus sends: Authorization: Bearer <contents of this file>
credentials_file: /etc/prometheus/secrets/crafty_token
static_configs:
- targets:
- '127.0.0.1:8443'
```
=== "Scrape host metrics: `/metrics/host`"
```yaml
- job_name: 'crafty-host'
scheme: https
metrics_path: /metrics/host
scrape_interval: 5s
tls_config:
# For self-signed certs while testing – better to install a CA in production
insecure_skip_verify: true
authorization:
type: Bearer
# Prometheus sends: Authorization: Bearer <contents of this file>
credentials_file: /etc/prometheus/secrets/crafty_token
static_configs:
- targets:
- '127.0.0.1:8443'
```
=== "Scrape a specific server: `/metrics/servers/{serverID}`"
```yaml
- job_name: 'crafty-server-ef3fb2d1'
scheme: https
metrics_path: /metrics/servers/ef3fb2d1-a94c-4d9b-8c65-c4274be706cb'
scrape_interval: 5s
tls_config:
# For self-signed certs while testing – better to install a CA in production
insecure_skip_verify: true
authorization:
type: Bearer
# Prometheus sends: Authorization: Bearer <contents of this file>
credentials_file: /etc/prometheus/secrets/crafty_token
static_configs:
- targets:
- '127.0.0.1:8443'
labels:
crafty_server_id: 'ef3fb2d1-a94c-4d9b-8c65-c4274be706cb'
crafty_server_name: 'ExampleServer'
```
=== "Scraping multiple servers"
```yaml
- job_name: 'crafty-servers'
scheme: https
scrape_interval: 5s
tls_config:
# For self-signed certs while testing – better to install a CA in production
insecure_skip_verify: true
authorization:
type: Bearer
# Prometheus sends: Authorization: Bearer <contents of this file>
credentials_file: /etc/prometheus/secrets/crafty_token
static_configs:
- targets:
- '127.0.0.1:8443'
labels:
__metrics_path__: '/metrics/servers/ef3fb2d1-a94c-4d9b-8c65-c4274be706cb'
crafty_server_name: 'Lobby'
- targets:
- '127.0.0.1:8443'
labels:
__metrics_path__: '/metrics/servers/another-server-id-here'
crafty_server_name: 'Survival'
```
With these metrics, system administrators can keep a close eye on server health, performance, and user activities, enabling proactive maintenance and swift response to any issues.

1
mkdocs.yml
View File

@@ -34,6 +34,7 @@ nav:
- Server Task Scheduler: pages/user-guide/task-scheduler.md
- Server Re-ordering: pages/user-guide/reorder-servers.md
- Server Webhooks: pages/user-guide/webhooks.md
- Open-Metrics (Prometheus): pages/user-guide/open-metrics.md
- Developer Guide:
- API Reference (v2): pages/developer-guide/api-reference/v2.md
- Contributing: