Operations
Monitoring
Structr provides several ways to monitor the health and performance of your instance: a web-based dashboard for interactive monitoring, and HTTP endpoints for integration with external monitoring systems like Prometheus and Grafana.
Dashboard Monitoring
The Admin UI Dashboard provides real-time monitoring capabilities:
- Server Log – Live view of the server log with configurable refresh interval
- Event Log – Structured view of API requests, authentication events, and transactions with timing breakdowns
- Threads – List of all running threads with the ability to interrupt or kill stuck threads
- Access Statistics – Filterable table of request statistics
See the Dashboard chapter for details on using these features.
System Resources
Structr monitors system resources to help you assess server capacity and diagnose performance issues. The Dashboard displays key metrics in the “About Structr” tab.
Available Metrics
| Metric | Description |
|---|---|
| Processors | Number of CPU cores available to the JVM |
| Free Memory | Currently unused heap memory |
| Total Memory | Heap memory currently allocated by the JVM |
| Max Memory | Maximum heap memory the JVM can allocate (configured via application.heap.max_size) |
| Uptime | Time since Structr started |
| Thread Count | Current number of active threads |
| Peak Thread Count | Highest thread count since startup |
| Daemon Thread Count | Number of daemon threads |
| CPU Load Average | System load average (1 minute) |
| Node Cache | Size and usage of the node cache |
| Relationship Cache | Size and usage of the relationship cache |
Interpreting Memory Values
The three memory values relate to each other as follows:
- Free Memory is the unused portion of Total Memory
- Total Memory grows up to Max Memory as needed
- If Free Memory stays consistently low while Total Memory equals Max Memory, consider increasing the heap size
Viewing System Resources
System resource information is available in two places:
- Dashboard – The “About Structr” tab shows processors, free memory, total memory, and max memory
- Health Check Endpoint – The
/structr/healthendpoint returns all metrics listed above in a machine-readable JSON format
HTTP Access Statistics
Structr automatically collects statistics about HTTP requests to your application. These statistics help you understand usage patterns, identify slow endpoints, and detect unusual access behavior.
Collected Metrics
For each endpoint (HTML pages and REST API), Structr tracks:
- Total request count
- Minimum response time
- Maximum response time
- Average response time
Statistics are aggregated per time interval to keep memory usage bounded while still providing useful historical data.
Viewing Statistics
Access statistics are available in two places:
- Dashboard – The “About Structr” tab shows a filterable table with request statistics grouped by timestamp, request count, and HTTP method
- Health Check Endpoint – The
/structr/healthendpoint includes response time statistics in thehtml:responseTimeandjson:responseTimesections
Configuration
Configure these settings in structr.conf or through the Configuration Interface:
| Setting | Default | Description |
|---|---|---|
application.stats.aggregation.interval | 60000 | Aggregation interval in milliseconds. Statistics are grouped into buckets of this size. |
Health Check Endpoint
The health check endpoint provides machine-readable status information for load balancers, container orchestration systems, and monitoring tools.
Endpoints
| Endpoint | Purpose |
|---|---|
/structr/health | Full health status in JSON format |
/structr/health/ready | Readiness probe (HTTP status only) |
Readiness Probe
The /structr/health/ready endpoint returns only an HTTP status code, making it suitable for Kubernetes readiness probes or load balancer health checks:
200 OK– Structr is ready to accept requests503 Service Unavailable– Structr is starting up, shutting down, or a deployment is in progress
Full Health Status
The /structr/health endpoint returns detailed status information in the application/health+json format:
- Memory utilization (free, max, total)
- CPU load average
- Uptime
- Thread counts (current, peak, daemon)
- Cache statistics (nodes, relationships)
- Response time statistics for HTML pages and REST endpoints
Access to the full health data is restricted by IP whitelist. Requests from non-whitelisted IPs receive only the HTTP status code.
Configuration
Configure these settings in structr.conf or through the Configuration Interface:
| Setting | Default | Description |
|---|---|---|
healthcheckservlet.path | /structr/health | Endpoint path |
healthcheckservlet.whitelist | 127.0.0.1, localhost, ::1 | IPs allowed to access full health data |
Prometheus Metrics
Structr exposes metrics in Prometheus format at /structr/metrics. This endpoint is designed for scraping by a Prometheus server.
Available Metrics
| Metric | Type | Description |
|---|---|---|
structr_http_requests_total | Counter | Total HTTP requests (labels: method, path, status) |
structr_http_request_duration_seconds | Histogram | Request duration (labels: method, path) |
In addition to Structr-specific metrics, standard JVM metrics are exposed (memory, garbage collection, threads, etc.).
Configuration
Configure these settings in structr.conf or through the Configuration Interface:
| Setting | Default | Description |
|---|---|---|
metricsservlet.path | /structr/metrics | Endpoint path |
metricsservlet.whitelist | 127.0.0.1, localhost, ::1 | IPs allowed to access metrics |
Prometheus Configuration
To scrape metrics from Structr, add a job to your Prometheus configuration:
scrape_configs:
- job_name: 'structr'
static_configs:
- targets: ['localhost:8082']
metrics_path: /structr/metrics
If Prometheus runs on a different machine, add its IP address to the whitelist in structr.conf:
metricsservlet.whitelist = 127.0.0.1, localhost, ::1, 10.0.0.50
Grafana Dashboard
A pre-built Grafana dashboard for Structr is available at grafana.com/grafana/dashboards/16770. You can import it using the dashboard ID 16770.
Query Histogram
The histogram endpoint provides detailed query performance analysis, useful for identifying slow queries and optimization opportunities.
Endpoint
/structr/histogram
Parameters
| Parameter | Description |
|---|---|
sort | Sort results by: total, count, min, max, avg (default: total) |
top | Number of results to return (default: 1000) |
reset | If present, clears the histogram data after returning results |
Example: /structr/histogram?sort=avg&top=100
Configuration
Configure these settings in structr.conf or through the Configuration Interface:
| Setting | Default | Description |
|---|---|---|
histogramservlet.path | /structr/histogram | Endpoint path |
histogramservlet.whitelist | 127.0.0.1, localhost, ::1 | IPs allowed to access histogram data |
Related Topics
- Dashboard - Interactive monitoring in the Admin UI
- Configuration - Server settings
- Maintenance - Maintenance mode for planned downtime