Initialize repository snapshot
This commit is contained in:
Vault Sovereign
101
docs/observability/README.md
Normal file
101
docs/observability/README.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# Observability - VaultMesh
|
||||
|
||||
This directory contains a Prometheus exporter for VaultMesh and a Grafana dashboard.
|
||||
|
||||
## Metrics Exposed
|
||||
|
||||
| Metric | Type | Labels | Description |
|
||||
|--------|------|--------|-------------|
|
||||
| `vaultmesh_receipts_total` | Counter | `module` | Number of receipts emitted |
|
||||
| `vaultmesh_receipts_failed_total` | Counter | `module`, `reason` | Failed receipt emissions |
|
||||
| `vaultmesh_anchor_age_seconds` | Gauge | - | Seconds since last guardian anchor |
|
||||
| `vaultmesh_emit_seconds` | Histogram | `module` | Receipt emit latency |
|
||||
|
||||
## Quick Start (Local)
|
||||
|
||||
### Option 1: Run exporter directly
|
||||
|
||||
```bash
|
||||
cd vaultmesh-observability
|
||||
cargo run --release
|
||||
```
|
||||
|
||||
Exposes metrics at `http://0.0.0.0:9108/metrics`
|
||||
|
||||
### Option 2: Using Docker Compose
|
||||
|
||||
```bash
|
||||
cd docs/observability
|
||||
docker-compose up --build
|
||||
```
|
||||
|
||||
Services:
|
||||
- **Exporter**: http://localhost:9108/metrics
|
||||
- **Prometheus**: http://localhost:9090
|
||||
- **Grafana**: http://localhost:3000 (admin/admin)
|
||||
|
||||
## Importing the Dashboard
|
||||
|
||||
1. Open Grafana at http://localhost:3000
|
||||
2. Go to Dashboards → Import
|
||||
3. Upload `dashboards/receipts.json`
|
||||
4. Select the Prometheus data source
|
||||
5. Click Import
|
||||
|
||||
## CI Smoke Test
|
||||
|
||||
The smoke test verifies the exporter responds on `/metrics`:
|
||||
|
||||
```bash
|
||||
cargo test -p vaultmesh-observability --tests
|
||||
```
|
||||
|
||||
Add to `.gitlab-ci.yml`:
|
||||
|
||||
```yaml
|
||||
observability-smoke:
|
||||
stage: test
|
||||
image: rust:1.75
|
||||
script:
|
||||
- cargo test -p vaultmesh-observability --tests -- --nocapture
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `VAULTMESH_METRICS_ADDR` | `0.0.0.0:9108` | Listen address for metrics server |
|
||||
|
||||
## Guardian Metrics Integration Test
|
||||
|
||||
The Guardian engine has an integration test that verifies metrics are emitted after anchors:
|
||||
|
||||
```bash
|
||||
cargo test -p vaultmesh-guardian --features metrics --test metrics_integration
|
||||
```
|
||||
|
||||
This test:
|
||||
- Starts ObservabilityEngine on a test port
|
||||
- Creates Guardian with observability enabled
|
||||
- Performs an anchor
|
||||
- Verifies `/metrics` contains `vaultmesh_anchor_age_seconds 0` (fresh anchor)
|
||||
|
||||
## Integration with Other Engines
|
||||
|
||||
Other VaultMesh engines can record metrics by calling:
|
||||
|
||||
```rust
|
||||
use vaultmesh_observability::ObservabilityEngine;
|
||||
use std::sync::Arc;
|
||||
|
||||
let engine = Arc::new(ObservabilityEngine::new());
|
||||
|
||||
// Record successful receipt emission
|
||||
engine.observe_emitted("guardian", latency_seconds);
|
||||
|
||||
// Record failure
|
||||
engine.observe_failed("treasury", "io_error");
|
||||
|
||||
// Update anchor age (0 = just anchored)
|
||||
engine.set_anchor_age(0.0);
|
||||
```
|
||||
366
docs/observability/dashboards/receipts.json
Normal file
366
docs/observability/dashboards/receipts.json
Normal file
@@ -0,0 +1,366 @@
|
||||
{
|
||||
"annotations": {
|
||||
"list": []
|
||||
},
|
||||
"editable": true,
|
||||
"fiscalYearStartMonth": 0,
|
||||
"graphTooltip": 0,
|
||||
"id": null,
|
||||
"links": [],
|
||||
"liveNow": false,
|
||||
"panels": [
|
||||
{
|
||||
"datasource": {
|
||||
"type": "prometheus",
|
||||
"uid": "prometheus"
|
||||
},
|
||||
"fieldConfig": {
|
||||
"defaults": {
|
||||
"color": {
|
||||
"mode": "palette-classic"
|
||||
},
|
||||
"custom": {
|
||||
"axisCenteredZero": false,
|
||||
"axisColorMode": "text",
|
||||
"axisLabel": "",
|
||||
"axisPlacement": "auto",
|
||||
"barAlignment": 0,
|
||||
"drawStyle": "line",
|
||||
"fillOpacity": 10,
|
||||
"gradientMode": "none",
|
||||
"hideFrom": {
|
||||
"legend": false,
|
||||
"tooltip": false,
|
||||
"viz": false
|
||||
},
|
||||
"lineInterpolation": "linear",
|
||||
"lineWidth": 1,
|
||||
"pointSize": 5,
|
||||
"scaleDistribution": {
|
||||
"type": "linear"
|
||||
},
|
||||
"showPoints": "auto",
|
||||
"spanNulls": false,
|
||||
"stacking": {
|
||||
"group": "A",
|
||||
"mode": "none"
|
||||
},
|
||||
"thresholdsStyle": {
|
||||
"mode": "off"
|
||||
}
|
||||
},
|
||||
"mappings": [],
|
||||
"thresholds": {
|
||||
"mode": "absolute",
|
||||
"steps": [
|
||||
{
|
||||
"color": "green",
|
||||
"value": null
|
||||
}
|
||||
]
|
||||
},
|
||||
"unit": "short"
|
||||
},
|
||||
"overrides": []
|
||||
},
|
||||
"gridPos": {
|
||||
"h": 8,
|
||||
"w": 24,
|
||||
"x": 0,
|
||||
"y": 0
|
||||
},
|
||||
"id": 1,
|
||||
"options": {
|
||||
"legend": {
|
||||
"calcs": [],
|
||||
"displayMode": "list",
|
||||
"placement": "bottom",
|
||||
"showLegend": true
|
||||
},
|
||||
"tooltip": {
|
||||
"mode": "single",
|
||||
"sort": "none"
|
||||
}
|
||||
},
|
||||
"targets": [
|
||||
{
|
||||
"datasource": {
|
||||
"type": "prometheus",
|
||||
"uid": "prometheus"
|
||||
},
|
||||
"expr": "sum by(module) (rate(vaultmesh_receipts_total[1m]))",
|
||||
"legendFormat": "{{module}}",
|
||||
"refId": "A"
|
||||
}
|
||||
],
|
||||
"title": "Receipts Emitted Rate (by module)",
|
||||
"type": "timeseries"
|
||||
},
|
||||
{
|
||||
"datasource": {
|
||||
"type": "prometheus",
|
||||
"uid": "prometheus"
|
||||
},
|
||||
"fieldConfig": {
|
||||
"defaults": {
|
||||
"color": {
|
||||
"mode": "palette-classic"
|
||||
},
|
||||
"custom": {
|
||||
"axisCenteredZero": false,
|
||||
"axisColorMode": "text",
|
||||
"axisLabel": "",
|
||||
"axisPlacement": "auto",
|
||||
"barAlignment": 0,
|
||||
"drawStyle": "bars",
|
||||
"fillOpacity": 50,
|
||||
"gradientMode": "none",
|
||||
"hideFrom": {
|
||||
"legend": false,
|
||||
"tooltip": false,
|
||||
"viz": false
|
||||
},
|
||||
"lineInterpolation": "linear",
|
||||
"lineWidth": 1,
|
||||
"pointSize": 5,
|
||||
"scaleDistribution": {
|
||||
"type": "linear"
|
||||
},
|
||||
"showPoints": "auto",
|
||||
"spanNulls": false,
|
||||
"stacking": {
|
||||
"group": "A",
|
||||
"mode": "none"
|
||||
},
|
||||
"thresholdsStyle": {
|
||||
"mode": "off"
|
||||
}
|
||||
},
|
||||
"mappings": [],
|
||||
"thresholds": {
|
||||
"mode": "absolute",
|
||||
"steps": [
|
||||
{
|
||||
"color": "red",
|
||||
"value": null
|
||||
}
|
||||
]
|
||||
},
|
||||
"unit": "short"
|
||||
},
|
||||
"overrides": []
|
||||
},
|
||||
"gridPos": {
|
||||
"h": 6,
|
||||
"w": 12,
|
||||
"x": 0,
|
||||
"y": 8
|
||||
},
|
||||
"id": 2,
|
||||
"options": {
|
||||
"legend": {
|
||||
"calcs": [],
|
||||
"displayMode": "list",
|
||||
"placement": "bottom",
|
||||
"showLegend": true
|
||||
},
|
||||
"tooltip": {
|
||||
"mode": "single",
|
||||
"sort": "none"
|
||||
}
|
||||
},
|
||||
"targets": [
|
||||
{
|
||||
"datasource": {
|
||||
"type": "prometheus",
|
||||
"uid": "prometheus"
|
||||
},
|
||||
"expr": "sum by(module, reason) (rate(vaultmesh_receipts_failed_total[1m]))",
|
||||
"legendFormat": "{{module}} - {{reason}}",
|
||||
"refId": "A"
|
||||
}
|
||||
],
|
||||
"title": "Receipt Failures",
|
||||
"type": "timeseries"
|
||||
},
|
||||
{
|
||||
"datasource": {
|
||||
"type": "prometheus",
|
||||
"uid": "prometheus"
|
||||
},
|
||||
"fieldConfig": {
|
||||
"defaults": {
|
||||
"color": {
|
||||
"mode": "thresholds"
|
||||
},
|
||||
"mappings": [],
|
||||
"thresholds": {
|
||||
"mode": "absolute",
|
||||
"steps": [
|
||||
{
|
||||
"color": "green",
|
||||
"value": null
|
||||
}
|
||||
]
|
||||
},
|
||||
"unit": "dateTimeAsIso"
|
||||
},
|
||||
"overrides": []
|
||||
},
|
||||
"gridPos": {
|
||||
"h": 6,
|
||||
"w": 12,
|
||||
"x": 12,
|
||||
"y": 8
|
||||
},
|
||||
"id": 3,
|
||||
"options": {
|
||||
"colorMode": "value",
|
||||
"graphMode": "none",
|
||||
"justifyMode": "auto",
|
||||
"orientation": "auto",
|
||||
"reduceOptions": {
|
||||
"calcs": [
|
||||
"lastNotNull"
|
||||
],
|
||||
"fields": "",
|
||||
"values": false
|
||||
},
|
||||
"textMode": "auto"
|
||||
},
|
||||
"pluginVersion": "10.1.0",
|
||||
"targets": [
|
||||
{
|
||||
"datasource": {
|
||||
"type": "prometheus",
|
||||
"uid": "prometheus"
|
||||
},
|
||||
"expr": "vaultmesh_anchor_age_seconds * 1000",
|
||||
"legendFormat": "Last Anchor",
|
||||
"refId": "A"
|
||||
}
|
||||
],
|
||||
"title": "Last Anchor Timestamp",
|
||||
"type": "stat"
|
||||
},
|
||||
{
|
||||
"datasource": {
|
||||
"type": "prometheus",
|
||||
"uid": "prometheus"
|
||||
},
|
||||
"fieldConfig": {
|
||||
"defaults": {
|
||||
"color": {
|
||||
"mode": "palette-classic"
|
||||
},
|
||||
"custom": {
|
||||
"axisCenteredZero": false,
|
||||
"axisColorMode": "text",
|
||||
"axisLabel": "",
|
||||
"axisPlacement": "auto",
|
||||
"barAlignment": 0,
|
||||
"drawStyle": "line",
|
||||
"fillOpacity": 10,
|
||||
"gradientMode": "none",
|
||||
"hideFrom": {
|
||||
"legend": false,
|
||||
"tooltip": false,
|
||||
"viz": false
|
||||
},
|
||||
"lineInterpolation": "linear",
|
||||
"lineWidth": 1,
|
||||
"pointSize": 5,
|
||||
"scaleDistribution": {
|
||||
"type": "linear"
|
||||
},
|
||||
"showPoints": "auto",
|
||||
"spanNulls": false,
|
||||
"stacking": {
|
||||
"group": "A",
|
||||
"mode": "none"
|
||||
},
|
||||
"thresholdsStyle": {
|
||||
"mode": "off"
|
||||
}
|
||||
},
|
||||
"mappings": [],
|
||||
"thresholds": {
|
||||
"mode": "absolute",
|
||||
"steps": [
|
||||
{
|
||||
"color": "green",
|
||||
"value": null
|
||||
}
|
||||
]
|
||||
},
|
||||
"unit": "s"
|
||||
},
|
||||
"overrides": []
|
||||
},
|
||||
"gridPos": {
|
||||
"h": 6,
|
||||
"w": 24,
|
||||
"x": 0,
|
||||
"y": 14
|
||||
},
|
||||
"id": 4,
|
||||
"options": {
|
||||
"legend": {
|
||||
"calcs": [
|
||||
"mean",
|
||||
"max"
|
||||
],
|
||||
"displayMode": "table",
|
||||
"placement": "right",
|
||||
"showLegend": true
|
||||
},
|
||||
"tooltip": {
|
||||
"mode": "single",
|
||||
"sort": "none"
|
||||
}
|
||||
},
|
||||
"targets": [
|
||||
{
|
||||
"datasource": {
|
||||
"type": "prometheus",
|
||||
"uid": "prometheus"
|
||||
},
|
||||
"expr": "histogram_quantile(0.95, sum by(le, module) (rate(vaultmesh_emit_seconds_bucket[5m])))",
|
||||
"legendFormat": "p95 {{module}}",
|
||||
"refId": "A"
|
||||
},
|
||||
{
|
||||
"datasource": {
|
||||
"type": "prometheus",
|
||||
"uid": "prometheus"
|
||||
},
|
||||
"expr": "histogram_quantile(0.50, sum by(le, module) (rate(vaultmesh_emit_seconds_bucket[5m])))",
|
||||
"legendFormat": "p50 {{module}}",
|
||||
"refId": "B"
|
||||
}
|
||||
],
|
||||
"title": "Receipt Emit Latency (p50/p95)",
|
||||
"type": "timeseries"
|
||||
}
|
||||
],
|
||||
"refresh": "5s",
|
||||
"schemaVersion": 38,
|
||||
"style": "dark",
|
||||
"tags": [
|
||||
"vaultmesh",
|
||||
"receipts"
|
||||
],
|
||||
"templating": {
|
||||
"list": []
|
||||
},
|
||||
"time": {
|
||||
"from": "now-1h",
|
||||
"to": "now"
|
||||
},
|
||||
"timepicker": {},
|
||||
"timezone": "",
|
||||
"title": "VaultMesh Receipts Overview",
|
||||
"uid": "vaultmesh-receipts",
|
||||
"version": 1,
|
||||
"weekStart": ""
|
||||
}
|
||||
34
docs/observability/docker-compose.yml
Normal file
34
docs/observability/docker-compose.yml
Normal file
@@ -0,0 +1,34 @@
|
||||
version: "3.8"
|
||||
|
||||
services:
|
||||
exporter:
|
||||
build:
|
||||
context: ../..
|
||||
dockerfile: vaultmesh-observability/Dockerfile
|
||||
image: vaultmesh-observability:local
|
||||
ports:
|
||||
- "9108:9108"
|
||||
environment:
|
||||
- VAULTMESH_METRICS_ADDR=0.0.0.0:9108
|
||||
|
||||
prometheus:
|
||||
image: prom/prometheus:v2.47.0
|
||||
volumes:
|
||||
- ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
|
||||
ports:
|
||||
- "9090:9090"
|
||||
depends_on:
|
||||
- exporter
|
||||
|
||||
grafana:
|
||||
image: grafana/grafana:10.1.0
|
||||
environment:
|
||||
- GF_SECURITY_ADMIN_PASSWORD=admin
|
||||
- GF_USERS_ALLOW_SIGN_UP=false
|
||||
volumes:
|
||||
- ./dashboards:/var/lib/grafana/dashboards:ro
|
||||
- ./grafana-provisioning:/etc/grafana/provisioning:ro
|
||||
ports:
|
||||
- "3000:3000"
|
||||
depends_on:
|
||||
- prometheus
|
||||
@@ -0,0 +1,12 @@
|
||||
apiVersion: 1
|
||||
|
||||
providers:
|
||||
- name: 'VaultMesh'
|
||||
orgId: 1
|
||||
folder: 'VaultMesh'
|
||||
folderUid: 'vaultmesh'
|
||||
type: file
|
||||
disableDeletion: false
|
||||
editable: true
|
||||
options:
|
||||
path: /var/lib/grafana/dashboards
|
||||
@@ -0,0 +1,9 @@
|
||||
apiVersion: 1
|
||||
|
||||
datasources:
|
||||
- name: Prometheus
|
||||
type: prometheus
|
||||
access: proxy
|
||||
url: http://prometheus:9090
|
||||
isDefault: true
|
||||
uid: prometheus
|
||||
9
docs/observability/prometheus.yml
Normal file
9
docs/observability/prometheus.yml
Normal file
@@ -0,0 +1,9 @@
|
||||
global:
|
||||
scrape_interval: 5s
|
||||
evaluation_interval: 5s
|
||||
|
||||
scrape_configs:
|
||||
- job_name: 'vaultmesh_observability'
|
||||
static_configs:
|
||||
- targets: ['exporter:9108']
|
||||
metrics_path: /metrics
|
||||
Reference in New Issue
Block a user