UPS Monitoring

[domalab]

UPS Monitoring GraphQL

Is your feature request related to a problem?

Yes, this feature request addresses critical gaps in the Unraid GraphQL API regarding UPS monitoring and power management capabilities:

1. Missing UPS monitoring endpoints: The current Unraid GraphQL API lacks UPS monitoring queries, making it impossible for developers to build applications that monitor UPS status, battery levels, and power conditions through the official API.

2. No UPS configuration mutations: There are no GraphQL mutations available for configuring UPS connections, monitoring settings, or power management parameters, forcing developers to use external tools or direct system calls.

3. Absence of real-time UPS subscriptions: The GraphQL API doesn't provide subscription endpoints for real-time UPS monitoring, preventing developers from building responsive applications that react to power events and battery status changes.

4. Limited power management integration: API consumers cannot query UPS power events, battery health, or estimated runtime through GraphQL, making it difficult to build comprehensive power management applications.

5. No standardized UPS data models: Without official GraphQL schemas for UPS data, developers must create their own inconsistent data structures, leading to fragmented ecosystem solutions.

6. Missing multi-UPS support: The API doesn't provide a unified interface for multiple UPS devices, requiring separate implementations for different UPS configurations.

Describe the solution you'd like

I would like comprehensive UPS monitoring capabilities added to the Unraid GraphQL API that provides:

GraphQL Schema Extensions

• UPS Data Types: Complete GraphQL type definitions for UPS devices, battery information, power metrics, input/output data, and configuration options
• Resource Enum Extension: Addition of UPS to the existing Resource enum for permission management
• Input Types: Configuration input types for UPS connection settings, monitoring parameters, and alert thresholds

Query Operations

• upsDevices: Query to retrieve all configured UPS devices with current status including battery level, estimated runtime, load percentage, and power conditions
• upsDeviceById(id: String!): Query to get detailed information for a specific UPS device including historical data and configuration
• UPS power event queries: Retrieve power event logs, battery performance history, and power quality metrics
• Connection status queries: Check UPS connectivity and communication status

Mutation Operations

• configureUps(config: UpsConfigInput!): Mutation to configure UPS connection parameters, monitoring settings, and alert thresholds
• testUpsConnection(config: UpsConfigInput!): Mutation to test UPS connectivity and validate configuration settings
• UPS management mutations: Start/stop monitoring, refresh device information, and update settings

Subscription Operations

• upsUpdates: Real-time subscription for UPS status updates including battery level, power conditions, and device health
• upsAlerts: Subscription for critical UPS alerts such as power outages, low battery warnings, and device faults
• upsPowerEvents: Subscription for power quality events and significant power condition changes

Multi-UPS API Support

• Unified GraphQL interface that supports multiple UPS devices in a single system
• Tool abstraction: Automatic detection and appropriate tool selection (Network UPS Tools, APC PowerChute)
• Consistent data models: Standardized GraphQL types that work across different UPS manufacturers and connection types

Example API Usage

# Query UPS devices
query GetUPSDevices {
  upsDevices {
    id
    name
    model
    status
    battery {
      chargeLevel
      estimatedRuntime
      health
    }
    power {
      inputVoltage
      outputVoltage
      loadPercentage
    }
  }
}

# Configure UPS
mutation ConfigureUPS($config: UpsConfigInput!) {
  configureUps(config: $config) {
    success
    message
    device {
      id
      name
      status
    }
  }
}

# Subscribe to UPS updates
subscription UPSUpdates {
  upsUpdates {
    id
    status
    battery {
      chargeLevel
      estimatedRuntime
    }
    alerts {
      type
      message
      severity
    }
  }
}

Additional context

GraphQL API Integration Details

The proposed UPS monitoring feature would integrate seamlessly with the existing Unraid GraphQL API:

• Type system integration: UPS monitoring types would follow existing Unraid GraphQL conventions and naming patterns
• Permission system: Uses existing Resource-based permissions with new UPS resource type
• Authentication: Leverages existing GraphQL authentication and authorization mechanisms
• Error handling: Follows established GraphQL error response patterns used throughout the Unraid API

Developer Use Cases

1. Power Management Applications: Developers can build comprehensive power management dashboards that monitor UPS status alongside system metrics
2. Mobile Monitoring Apps: Real-time UPS monitoring applications using GraphQL subscriptions for live battery and power updates
3. Automation Tools: Scripts and applications that monitor UPS health and automatically respond to power events
4. Infrastructure Management: Multi-server monitoring tools that track UPS status across multiple Unraid systems
5. Alert Integration: Applications that integrate UPS alerts with existing notification and monitoring systems

API Consumer Benefits

• Type Safety: Complete TypeScript/GraphQL type definitions for all UPS monitoring data
• Real-time Updates: WebSocket-based subscriptions for responsive power monitoring applications
• Unified Interface: Single API endpoint for all UPS devices and connection types
• Query Flexibility: GraphQL's query language allows precise data fetching to minimize bandwidth usage
• Developer Experience: Consistent with existing Unraid GraphQL patterns and documentation

Implementation Considerations

• Backward Compatibility: New GraphQL types and fields won't affect existing API consumers
• Performance Impact: Efficient data fetching with configurable polling intervals and intelligent caching
• Schema Versioning: UPS monitoring additions follow Unraid's GraphQL schema versioning strategy
• Documentation: Complete GraphQL schema documentation with examples and best practices

Integration with Existing Unraid Features

• System Management: UPS status integrated with existing system health GraphQL queries
• Notification System: UPS alerts integrated with existing Unraid notification GraphQL subscriptions
• User Management: UPS monitoring permissions integrated with existing user role system
• Configuration Management: UPS settings integrated with existing system configuration APIs

Environment (if relevant)

Unraid OS Version: 7.1.2 (requires existing GraphQL API infrastructure)

API Dependencies:

• Existing Unraid GraphQL API framework
• Current authentication and authorization system
• Established PubSub infrastructure for subscriptions
• Resource-based permission system

Hardware Requirements:

• One or more UPS devices (USB, serial, or network-connected)
• Compatible UPS with monitoring capabilities
• Sufficient system resources for UPS monitoring overhead

Software Dependencies:

• Network UPS Tools (NUT) for most UPS devices
• APC PowerChute for APC-specific features (optional)
• USB or serial drivers for direct-connected UPS devices
• Automatic tool detection and configuration

GraphQL Schema Requirements:

• Compatible with existing Unraid GraphQL schema versioning
• TypeScript code generation support for client applications
• Schema introspection support for development tools

Pre-submission Checklist

• I have searched existing issues to ensure this feature hasn't already been requested
• This is not an Unraid Connect related feature (if it is, please submit via the support form instead)
• I have provided clear examples or use cases for the feature
• I have focused specifically on GraphQL API extensions and capabilities
• I have considered alternative API approaches and explained why GraphQL is preferred
• I have provided detailed GraphQL schema examples and integration patterns
• I have specified API dependencies and compatibility requirements
• I have addressed how this integrates with existing Unraid GraphQL infrastructure

[pujitm]

heard, thanks for the write up, much appreciated.

[elibosley]

This is added in v4.12.0!