unpoller/.github/copilot-instructions.md

UnPoller - GitHub Copilot Instructions

Project Overview

UnPoller is a Go application that collects metrics and events from UniFi network controllers and exports them to monitoring backends (InfluxDB, Prometheus, Loki, DataDog, MySQL). The application uses a plugin-based architecture with a generic core.

Architecture

Plugin System

• Core Library (pkg/poller/): Generic plugin system with input/output interfaces
• Input Plugins: Collect data (e.g., pkg/inputunifi/)
• Output Plugins: Export data to backends (e.g., pkg/influxunifi/, pkg/promunifi/)
• Plugin Discovery: Automatic via blank imports in main.go

Key Interfaces

Input Interface:

type Input interface {
    GetMetrics() (*Metrics, error)
    GetEvents() (*Events, error)
}

Output Interface:

type Output interface {
    WriteMetrics(*Metrics) error
    WriteEvents(*Events) error
}

Code Style

Go Conventions

• Go 1.25.5+
• Use gofmt formatting
• Follow .golangci.yaml linting rules
• Enabled linters: nlreturn, revive, tagalign, testpackage, wsl_v5

Naming

• Packages: lowercase
• Exported: PascalCase
• Unexported: camelCase
• Errors: Always err, check immediately

Error Handling

if err != nil {
    return fmt.Errorf("context: %w", err)
}

Configuration

All config structs must include format tags:

type Config struct {
    Field string `json:"field" toml:"field" xml:"field" yaml:"field"`
}

Environment variables use UP_ prefix.

Common Patterns

Plugin Registration

func init() {
    poller.RegisterInput(&Input{})
    // or
    poller.RegisterOutput(&Output{})
}

Device Type Reporting

Each output plugin has device-specific functions:

• UAP() - Access Points
• USG() - Security Gateways
• USW() - Switches
• UDM() - Dream Machines
• UXG() - Next-Gen Gateways
• UBB() - Building Bridges
• UCI() - Industrial devices
• PDU() - Power Distribution Units

Adding New Plugin

1. Create package in pkg/
2. Implement Input or Output interface
3. Register in init()
4. Add blank import to main.go
5. Add config struct with tags
6. Create README.md

Dependencies

Core

• github.com/unpoller/unifi/v5 - UniFi API (local: /Users/briangates/unifi)
• golift.io/cnfg - Configuration
• golift.io/cnfgfile - Config parsing
• github.com/spf13/pflag - CLI flags

Outputs

• InfluxDB: github.com/influxdata/influxdb1-client, github.com/influxdata/influxdb-client-go/v2
• Prometheus: github.com/prometheus/client_golang
• DataDog: github.com/DataDog/datadog-go/v5
• Loki: Custom HTTP client

Important Notes

• pkg/poller core is generic - no UniFi/backend knowledge
• Support Windows, macOS, Linux, BSD
• Configuration: TOML (default), JSON, YAML, env vars
• Always check and return errors
• Use context.Context for cancellable operations
• Tests in _test packages
• Use github.com/stretchr/testify for assertions

When Writing Code

1. Follow existing plugin patterns
2. Keep core library generic
3. Check all errors
4. Document exported functions
5. Write tests in _test packages
6. Consider cross-platform compatibility
7. Use structured logging
8. Respect timeouts and deadlines