Health Check Endpoint

Referenced Files in This Document - health.py - server.py - dependencies.py - manager.py - base.py - engine.py - session.py - config.py - init.py

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document provides API documentation for the health check endpoint. It covers the GET /health endpoint, including HTTP method, URL pattern, response format, and the underlying health check mechanism. It explains how the system verifies service availability, database connectivity, and blockchain provider status. It also includes examples of successful responses, potential error scenarios, integration guidelines for load balancers and monitoring systems, and scheduling/alerting recommendations.

Project Structure

The health check endpoint is defined as a FastAPI route and registered at the application level. The endpoint itself returns a minimal JSON payload indicating service status. The broader system initializes blockchain providers and an HD wallet during application startup, which indirectly contributes to overall system health.

graph TB A["server.py
FastAPI app"] --> B["health.py
health_router"] A --> C["dependencies.py
get_blockchains(), get_hdwallet()"] A --> D["manager.py
get_blockchains()"] D --> E["base.py
BlockchainBase.is_connected()"] A --> F["engine.py
SQLAlchemy async engine"] F --> G["session.py
SessionLocal"] A --> H["config.py
Settings"]

Diagram sources - server.py - health.py - dependencies.py - manager.py - base.py - engine.py - session.py - config.py

Section sources - server.py - health.py - dependencies.py - manager.py - base.py - engine.py - session.py - config.py

Core Components

  • Health endpoint definition: The health endpoint is defined as a GET route at /health and returns a simple JSON object with a status field.
  • Application registration: The health router is included in the FastAPI application instance.
  • Runtime dependencies: The health endpoint does not depend on blockchain or database connections at runtime; however, the application lifecycle initializes blockchain providers and an HD wallet, which can influence overall system health.

Key implementation references: - Health route definition and response: health.py - Application registration of health router: server.py - Blockchain initialization during app lifespan: server.py - Blockchain provider factory: manager.py - Blockchain connectivity check method: base.py

Section sources - health.py - server.py - manager.py - base.py

Architecture Overview

The health check endpoint is part of the FastAPI application and is registered at startup. It does not perform explicit checks against the database or blockchain providers at request time. Instead, it relies on the application’s lifecycle to initialize resources that contribute to overall system health.

sequenceDiagram participant Client as "Client" participant App as "FastAPI App" participant Router as "health_router" participant Handler as "health_check()" participant DB as "Database Engine" participant BC as "Blockchain Providers" Client->>App : "GET /health" App->>Router : "Route dispatch" Router->>Handler : "Invoke handler" Handler-->>Client : "{ \"status\" : \"ok\" }" Note over App,DB : "Database engine initialized at startup" Note over App,BC : "Blockchain providers initialized at startup"

Diagram sources - server.py - health.py - engine.py - manager.py

Detailed Component Analysis

Health Endpoint Definition

  • HTTP Method: GET
  • URL Pattern: /health
  • Route Registration: Included in the FastAPI app instance.
  • Response Format: JSON object with a single field indicating service status.

Behavior and response: - The handler returns a JSON object with a status field set to an indicator of service health. - The current implementation returns a simple success indicator without detailed subsystem checks.

Integration references: - Route definition: health.py - Application registration: server.py

Section sources - health.py - server.py

Health Check Mechanism

  • Service Availability: The endpoint confirms the API server is reachable and responding.
  • Database Connectivity: The application initializes the database engine at startup; while the health endpoint does not explicitly check the database at request time, the presence of a working engine indicates connectivity.
  • Blockchain Provider Status: The application initializes blockchain providers during startup. The health endpoint does not perform live checks against blockchain nodes; however, the existence of initialized providers suggests readiness.

Runtime initialization highlights: - Blockchain providers are created and stored in app state during lifespan. - An HD wallet manager is initialized and stored in app state. - Background workers are started during lifespan.

References: - Lifespan initialization: server.py - Blockchain provider factory: manager.py - Base blockchain connectivity method: base.py - Database engine initialization: engine.py

Section sources - server.py - manager.py - base.py - engine.py

Response Format

  • Content-Type: application/json
  • Body: A JSON object containing a status field indicating service health.
  • Example successful response body:
  • {"status": "ok"}

Note: The current implementation returns a simple success indicator. There are no explicit fields for database or blockchain provider status in the response.

References: - Handler response: health.py

Section sources - health.py

Error Scenarios

  • Application Initialization Failure: If the application fails to initialize during startup, the health endpoint will not be available until initialization completes successfully.
  • Missing Runtime Dependencies: If blockchain providers or the HD wallet manager are not initialized in app state, dependent routes may fail, but the health endpoint itself does not depend on these at runtime.
  • Database Engine Issues: If the database engine fails to initialize, dependent routes requiring database access will fail, but the health endpoint does not explicitly check the database at request time.

Operational references: - Lifespan initialization and error propagation: server.py - Blockchain provider initialization: manager.py - Database engine initialization: engine.py

Section sources - server.py - manager.py - engine.py

Integration Guidelines

  • Load Balancers and Proxies:
  • Configure health probes to target GET /health.
  • Use a short timeout (e.g., 5–10 seconds) to quickly detect unresponsive instances.
  • Set acceptable failure thresholds (e.g., 2–3 consecutive failures) before marking an instance unhealthy.
  • Monitoring Systems:
  • Treat HTTP 200 responses from /health as healthy.
  • Track latency metrics for /health requests to detect performance degradation.
  • Correlate with application logs for deeper diagnostics.
  • Container Orchestration Platforms:
  • Kubernetes: Use livenessProbe and readinessProbe pointing to /health.
  • Docker Compose: Use healthcheck with interval, timeout, and retries aligned with platform defaults.
  • Platform-specific restart policies should be configured to handle transient failures.

[No sources needed since this section provides general guidance]

Scheduling Recommendations and Alerting Thresholds

  • Scheduling:
  • Probe interval: Every 10–30 seconds depending on environment stability.
  • Timeout: 5–10 seconds to avoid false positives during brief stalls.
  • Retries: 2–3 consecutive failures before marking unhealthy.
  • Alerting:
  • Immediate alerts for sustained unavailability of /health.
  • Secondary alerts for increased latency or non-200 responses.
  • Correlate with application logs and database/chain provider metrics.

[No sources needed since this section provides general guidance]

Dependency Analysis

The health endpoint depends on the application being initialized and the router being registered. It does not directly depend on database or blockchain checks at runtime.

graph TB H["health.py
health_check()"] --> R["server.py
include_router(health_router)"] R --> S["server.py
FastAPI app"] S --> L["server.py
lifespan()"] L --> M["manager.py
get_blockchains()"] M --> B["base.py
BlockchainBase.is_connected()"] S --> E["engine.py
async_engine"]

Diagram sources - health.py - server.py - manager.py - base.py - engine.py

Section sources - health.py - server.py - manager.py - base.py - engine.py

Performance Considerations

  • The health endpoint is lightweight and synchronous, returning immediately without external I/O.
  • For high-throughput environments, ensure the underlying FastAPI server is tuned appropriately.
  • Keep health probe intervals balanced to avoid unnecessary load while maintaining responsiveness.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

  • Endpoint Not Reachable:
  • Verify the health router is included in the application.
  • Confirm the application is running and listening on the expected port.
  • Unexpected Failures:
  • Check application logs for initialization errors during startup.
  • Validate that blockchain providers and the HD wallet manager are initialized in app state.
  • Review database engine initialization and connection settings.

Operational references: - Router registration: server.py - Lifespan initialization: server.py - Blockchain provider factory: manager.py - Database engine initialization: engine.py

Section sources - server.py - manager.py - engine.py

Conclusion

The GET /health endpoint provides a simple, fast indication of service availability. While it does not perform explicit checks against the database or blockchain providers at request time, the application’s startup lifecycle initializes these components, contributing to overall system health. Integrate the endpoint with load balancers, monitoring systems, and container orchestration platforms using the recommended scheduling and alerting thresholds.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

API Definition Summary

  • Method: GET
  • Path: /health
  • Content-Type: application/json
  • Response Body: {"status": "ok"}

Section sources - health.py