> ## Documentation Index
> Fetch the complete documentation index at: https://o1.network/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitoring

# 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

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/monitoring/logs
```

**Request Body (JSON):**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "host": "test-anvil-01",
  "application": "Anvil",
  "timespan": "1h",
  "search": "error",
  "setup": "binary",
  "limit": 50,
  "offset": 0
}
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/monitoring/logs/stream
```

**Request Body (JSON):**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "host": "test-anvil-01",
  "application": "Anvil",
  "timespan": "1h",
  "search": "error",
  "setup": "binary",
  "interval": 1
}
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "success": true,
  "streamUrl": "ws://localhost:3000/api/websocket/logs/stream-123456"
}
```

## Metrics Collection

### Get Metrics Snapshot

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/monitoring/metrics/snapshot
```

**Request Body (JSON):**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "host": "test-anvil-01",
  "application": "Anvil",
  "timespan": "1h",
  "metrics": ["cpu", "memory", "disk", "network"]
}
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/monitoring/metrics/stream
```

**Request Body (JSON):**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "host": "test-anvil-01",
  "application": "Anvil",
  "timespan": "1h",
  "metrics": ["cpu", "memory", "disk", "network"],
  "interval": 0.5,
  "setup": "binary"
}
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "success": true,
  "streamUrl": "ws://localhost:3000/api/websocket/metrics/stream-123456"
}
```

### Terminate All Metrics Processes

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/monitoring/metrics/terminate-all
```

**Request Body (JSON):**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "host": "test-anvil-01",
  "application": "Anvil"
}
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "success": true,
  "message": "All metrics processes terminated"
}
```

## Healthcheck Management

### Get Healthchecks

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/monitoring/healthchecks
```

**Query Parameters:**

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

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/monitoring/healthchecks
```

**Request Body (JSON):**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "host": "test-anvil-01",
  "application": "Anvil",
  "type": "http",
  "endpoint": "http://localhost:8545",
  "interval": 30,
  "timeout": 5,
  "enabled": true
}
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/monitoring/healthchecks/{id}/run
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/monitoring/inventory
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/monitoring/uptime?host=test-anvil-01&application=Anvil&setup=binary
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/monitoring/register-app
```

**Request Body (JSON):**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "node": "test-anvil-01",
  "application": "Anvil",
  "setup": "binary"
}
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "success": true,
  "message": "Background metrics collection started for Anvil on test-anvil-01",
  "data": {
    "node": "test-anvil-01",
    "application": "Anvil",
    "setup": "binary"
  }
}
```

### Unregister Application

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/monitoring/unregister-app
```

**Request Body (JSON):**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "node": "test-anvil-01",
  "application": "Anvil",
  "deleteMetrics": true
}
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "type": "log",
  "timestamp": "2024-01-15T10:30:00Z",
  "level": "INFO",
  "message": "Application heartbeat",
  "host": "test-anvil-01",
  "application": "Anvil"
}
```

### Metrics Stream Format

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "success": false,
  "error": "Application not found",
  "details": {
    "host": "test-anvil-01",
    "application": "non-existent-app"
  }
}
```

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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.