NetBeez Uptime API Proxy

A Docker containerized FastAPI application that exposes an /uptime.json endpoint for Grafana dashboards, aggregating uptime metrics from the NetBeez API.

Features

• Fetches target information from NetBeez API
• Calculates uptime percentages based on ping test results over the past 24 hours
• Implements 5-minute caching to reduce API load
• Handles pagination for large result sets
• Error resilient: logs errors and continues with available data

Environment Variables

The container requires the following environment variables:

• NB_API_KEY: Your NetBeez API key (required)
• TARGET_NAMES: Comma-separated list of target names, e.g., "DDE-66-E1,DDE-66-E2" (required)
• HOSTNAME: NetBeez server hostname, e.g., api.netbeez.net (required)

Building the Docker Image

docker build -t nb-api-proxy .

Running the Container

docker run -d \
  -p 8000:8000 \
  -e NB_API_KEY="your_api_key_here" \
  -e TARGET_NAMES="DDE-66-E1,DDE-66-E2" \
  -e HOSTNAME="my-beezkeeper.netbeezcloud.net" \
  --name nb-api-proxy \
  nb-api-proxy

API Endpoints

GET /uptime.json

Returns uptime data for all configured targets in JSON format.

Response Format:

[
  {
    "target_name": "DDE-66-E1",
    "destinations": [
      {
        "name": "DDE-66-E1-1",
        "address": "192.168.1.1",
        "uptime": 0.95
      },
      {
        "name": "DDE-66-E1-2",
        "address": "192.168.1.2",
        "uptime": 0.95
      }
    ]
  }
]

Caching: Results are cached for 5 minutes. Subsequent requests within the cache window will return cached data.

GET /health

Health check endpoint for container monitoring.

Response:

{
  "status": "healthy"
}

How It Works

1. Target Fetching: For each target name in TARGET_NAMES, the application fetches target information from NetBeez /targets.json endpoint.

2. Template Extraction: Extracts test_templates from each target and filters for templates with test_type="ping".

3. Ping Results: Fetches ping test results for the past 24 hours for all ping templates, handling pagination automatically.

4. Uptime Calculation: Calculates uptime as value_points / (value_points + error_points) for each destination.

5. Caching: Results are cached in memory for 5 minutes to reduce API load.

Error Handling

• All errors are logged to stdout/stderr
• The application continues processing even if some targets fail
• Partial data is returned if available
• An empty array is returned if all requests fail (but HTTP 200 status is maintained)

Development

Running Locally

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export NB_API_KEY="your_api_key"
export TARGET_NAMES="DDE-66-E1,DDE-66-E2"
export HOSTNAME="my-beezkeeper.netbeezcloud.net"

# Run the application
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Testing

# Test the endpoint
curl http://localhost:8000/uptime.json

# Test health endpoint
curl http://localhost:8000/health

License

MIT