Monitoring API Reference

Monitor your applications and infrastructure with real-time metrics, logs, and healthchecks through the Monitoring API. Provides comprehensive observability across your entire deployment.

Endpoints Overview

Method	Endpoint	Description
POST	`/api/monitoring/logs`	Get application logs
POST	`/api/monitoring/logs/stream`	Create log stream
GET	`/api/monitoring/inventory`	Get available hosts/apps
POST	`/api/monitoring/metrics/snapshot`	Get metrics snapshot
POST	`/api/monitoring/metrics/stream`	Create metrics stream
POST	`/api/monitoring/metrics/terminate-all`	Terminate all metrics processes
GET	`/api/monitoring/uptime`	Get uptime information

Log Management

Get Application Logs

POST /api/monitoring/logs

Request Body (JSON):

{
  "host": "test-anvil-01",
  "application": "Anvil",
  "timespan": "1h",
  "search": "error",
  "setup": "binary",
  "limit": 50,
  "offset": 0
}

Response:

{
  "success": true,
  "data": [
    {
      "timestamp": "2024-01-15T10:30:00Z",
      "level": "INFO",
      "message": "Application started successfully",
      "host": "test-anvil-01",
      "application": "Anvil"
    },
    {
      "timestamp": "2024-01-15T10:31:00Z",
      "level": "ERROR",
      "message": "Database connection failed",
      "host": "test-anvil-01",
      "application": "Anvil"
    }
  ],
  "summary": {
    "info": 45,
    "warning": 3,
    "error": 2,
    "total": 50
  },
  "total": 100,
  "hasMore": true
}

Create Log Stream

POST /api/monitoring/logs/stream

Request Body (JSON):

{
  "host": "test-anvil-01",
  "application": "Anvil",
  "timespan": "1h",
  "search": "error",
  "setup": "binary",
  "interval": 1
}

Response:

{
  "success": true,
  "streamUrl": "ws://localhost:3000/api/websocket/logs/stream-123456"
}

Metrics Collection

Get Metrics Snapshot

POST /api/monitoring/metrics/snapshot

Request Body (JSON):

{
  "host": "test-anvil-01",
  "application": "Anvil",
  "timespan": "1h",
  "metrics": ["cpu", "memory", "disk", "network"]
}

Response:

{
  "success": true,
  "data": {
    "cpu": {
      "usage": 45.2,
      "cores": 2,
      "load_average": [0.8, 0.7, 0.6]
    },
    "memory": {
      "total": 8192,
      "used": 4096,
      "free": 4096,
      "usage_percent": 50.0
    },
    "disk": {
      "total": 10737418240,
      "used": 5368709120,
      "free": 5368709120,
      "usage_percent": 50.0
    },
    "network": {
      "bytes_sent": 1024000,
      "bytes_recv": 2048000,
      "packets_sent": 1000,
      "packets_recv": 2000
    }
  },
  "source": "file"
}

Create Metrics Stream

POST /api/monitoring/metrics/stream

Request Body (JSON):

{
  "host": "test-anvil-01",
  "application": "Anvil",
  "timespan": "1h",
  "metrics": ["cpu", "memory", "disk", "network"],
  "interval": 0.5,
  "setup": "binary"
}

Response:

{
  "success": true,
  "streamUrl": "ws://localhost:3000/api/websocket/metrics/stream-123456"
}

Terminate All Metrics Processes

POST /api/monitoring/metrics/terminate-all

Request Body (JSON):

{
  "host": "test-anvil-01",
  "application": "Anvil"
}

Response:

{
  "success": true,
  "message": "All metrics processes terminated"
}

Healthcheck Management

Get Healthchecks

GET /api/monitoring/healthchecks

Query Parameters:

host (optional): Filter by host
application (optional): Filter by application
type (optional): Filter by type

Response:

{
  "success": true,
  "data": [
    {
      "id": "healthcheck-123456",
      "host": "test-anvil-01",
      "application": "Anvil",
      "type": "http",
      "endpoint": "http://localhost:8545",
      "interval": 30,
      "timeout": 5,
      "enabled": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Create Healthcheck

POST /api/monitoring/healthchecks

Request Body (JSON):

{
  "host": "test-anvil-01",
  "application": "Anvil",
  "type": "http",
  "endpoint": "http://localhost:8545",
  "interval": 30,
  "timeout": 5,
  "enabled": true
}

Response:

{
  "success": true,
  "data": {
    "id": "healthcheck-123456",
    "host": "test-anvil-01",
    "application": "Anvil",
    "type": "http",
    "endpoint": "http://localhost:8545",
    "interval": 30,
    "timeout": 5,
    "enabled": true,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Run Healthcheck

POST /api/monitoring/healthchecks/{id}/run

Response:

{
  "success": true,
  "data": {
    "id": "healthcheck-123456",
    "status": "healthy",
    "response_time": 0.125,
    "checked_at": "2024-01-15T10:30:00Z",
    "details": {
      "status_code": 200,
      "response": "OK"
    }
  }
}

System Information

Get Available Inventory

GET /api/monitoring/inventory

Response:

{
  "success": true,
  "data": {
    "hosts": [
      {
        "name": "test-anvil-01",
        "provider": "AWS",
        "region": "us-east-1",
        "applications": ["Anvil", "PostgreSQL"]
      }
    ],
    "applications": [
      {
        "name": "Anvil",
        "hosts": ["test-anvil-01"],
        "type": "blockchain"
      }
    ]
  }
}

Get Uptime Information

GET /api/monitoring/uptime?host=test-anvil-01&application=Anvil&setup=binary

Response:

{
  "success": true,
  "data": {
    "host": "test-anvil-01",
    "application": "Anvil",
    "uptime": {
      "days": 15,
      "hours": 6,
      "minutes": 30,
      "seconds": 45
    },
    "last_restart": "2024-01-01T10:30:00Z",
    "status": "running",
    "health": "healthy"
  }
}

Background Monitoring

Register Application for Background Collection

POST /api/monitoring/register-app

Request Body (JSON):

{
  "node": "test-anvil-01",
  "application": "Anvil",
  "setup": "binary"
}

Response:

{
  "success": true,
  "message": "Background metrics collection started for Anvil on test-anvil-01",
  "data": {
    "node": "test-anvil-01",
    "application": "Anvil",
    "setup": "binary"
  }
}

Unregister Application

POST /api/monitoring/unregister-app

Request Body (JSON):

{
  "node": "test-anvil-01",
  "application": "Anvil",
  "deleteMetrics": true
}

Response:

{
  "success": true,
  "message": "Background metrics collection stopped for Anvil on test-anvil-01",
  "metricsFileDeleted": true
}

WebSocket Streams

Monitoring API provides real-time streaming capabilities via WebSocket connections:

Log Stream Format

{
  "type": "log",
  "timestamp": "2024-01-15T10:30:00Z",
  "level": "INFO",
  "message": "Application heartbeat",
  "host": "test-anvil-01",
  "application": "Anvil"
}

Metrics Stream Format

{
  "type": "metrics",
  "timestamp": "2024-01-15T10:30:00Z",
  "host": "test-anvil-01",
  "application": "Anvil",
  "cpu": 45.2,
  "memory": 50.0,
  "disk": 25.5,
  "network_sent": 1024000,
  "network_recv": 2048000
}

Error Responses

{
  "success": false,
  "error": "Application not found",
  "details": {
    "host": "test-anvil-01",
    "application": "non-existent-app"
  }
}

{
  "success": false,
  "error": "Metrics collection failed",
  "details": {
    "host": "test-anvil-01",
    "application": "Anvil",
    "reason": "SSH connection timeout"
  }
}

Best Practices

Log Management

Use structured logging with proper levels
Implement log rotation and retention policies
Set up log aggregation for distributed systems
Monitor log patterns for anomalies

Metrics Collection

Collect metrics at appropriate intervals
Use consistent metric naming conventions
Implement metric aggregation and rollup
Set up alerting on critical metrics

Healthcheck Design

Design healthchecks to test critical functionality
Use appropriate timeouts and intervals
Implement circuit breaker patterns
Monitor healthcheck failures and trends

Performance Optimization

Use appropriate sampling rates for metrics
Implement caching for frequent queries
Optimize database queries and indexes
Monitor API performance and resource usage

For detailed schema definitions, refer to the OpenAPI specification published alongside the backend service.

Documentation Index

​Monitoring API Reference

​Endpoints Overview

​Log Management

​Get Application Logs

​Create Log Stream

​Metrics Collection

​Get Metrics Snapshot

​Create Metrics Stream

​Terminate All Metrics Processes

​Healthcheck Management

​Get Healthchecks

​Create Healthcheck

​Run Healthcheck

​System Information

​Get Available Inventory

​Get Uptime Information

​Background Monitoring

​Register Application for Background Collection

​Unregister Application

​WebSocket Streams

​Log Stream Format

​Metrics Stream Format

​Error Responses

​Best Practices

​Log Management

​Metrics Collection

​Healthcheck Design

​Performance Optimization

Monitoring API Reference

Endpoints Overview

Log Management

Get Application Logs

Create Log Stream

Metrics Collection

Get Metrics Snapshot

Create Metrics Stream

Terminate All Metrics Processes

Healthcheck Management

Get Healthchecks

Create Healthcheck

Run Healthcheck

System Information

Get Available Inventory

Get Uptime Information

Background Monitoring

Register Application for Background Collection

Unregister Application

WebSocket Streams

Log Stream Format

Metrics Stream Format

Error Responses

Best Practices

Log Management

Metrics Collection

Healthcheck Design

Performance Optimization