### Install macOS Launchd Service with All Options

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Configure the installation with all available options, including API secret, port, install directory, and service name.

```shell
curl -fsSL https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/macos/install.sh \
    | sudo bash -s -- \
        --api-secret "your-secret-key" \
        --port 59232 \
        --install-dir /usr/local/bin \
        --service-name com.bluewavelabs.capture
```

--------------------------------

### Install Linux Systemd Service with All Options

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Execute the installation script with all available options to customize the installation directory, port, service name, and API secret.

```shell
curl -fsSL https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/linux/install.sh \
    | sudo bash -s -- \
        --api-secret "your-secret-key" \
        --port 59232 \
        --install-dir /usr/local/bin \
        --service-name capture
```

--------------------------------

### Install Capture via Go Package

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Install the Bluewave Capture command-line tool using the Go package manager. This method requires Go to be installed on your system.

```shell
go install github.com/bluewave-labs/capture/cmd/capture@latest
```

--------------------------------

### Environment Variable Setup

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/config.md

Example of setting the PORT and API_SECRET environment variables for configuring the Capture application.

```bash
export PORT=59232
export API_SECRET=your-secure-secret-key
```

--------------------------------

### Install Dependencies

Source: https://github.com/bluewave-labs/capture/blob/develop/CONTRIBUTING.md

Install project dependencies using Go modules.

```bash
go mod tidy
```

--------------------------------

### Download and Install macOS Launchd Service Locally

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Download the installation script first, then execute it locally with optional arguments like the API secret.

```shell
curl -fsSL -o install.sh https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/macos/install.sh
sudo bash install.sh --api-secret "your-secret-key"
```

--------------------------------

### Install Linux Systemd Service (Basic)

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Use this command to download and run the installation script for the Linux systemd service. It automatically detects architecture and installs the latest release.

```shell
curl -fsSL https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/linux/install.sh | sudo bash
```

--------------------------------

### Install macOS Launchd Service with Default Options

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Download and run the installation script with a single command. The script will prompt for the API_SECRET if not provided.

```shell
curl -fsSL https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/macos/install.sh | sudo bash
```

--------------------------------

### Download and Run Linux Install Script Locally

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Download the installation script first, then execute it locally with the desired options. This allows for inspection of the script before running.

```shell
curl -fsSL -o install.sh https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/linux/install.sh
sudo bash install.sh --api-secret "your-secret-key"
```

--------------------------------

### Install Bluewave Capture Agent with All Parameters

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Installs the Capture agent with all available parameters including API secret, port, installation directory, and service name. Requires PowerShell 5.1+ and Administrator privileges.

```powershell
& ([scriptblock]::Create(
    (Invoke-RestMethod https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/windows/install.ps1)
)) -APISecret "your-secret-key" -Port 59232 -InstallDir "C:\Program Files\Capture" -ServiceName "capture"
```

--------------------------------

### Download and Install Bluewave Capture Agent Locally

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Downloads the installation script first, then executes it locally with the API secret. This method allows for offline installation or local modification of the script. Requires PowerShell 5.1+ and Administrator privileges.

```powershell
Invoke-RestMethod https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/windows/install.ps1 -OutFile install.ps1
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1 -APISecret "your-secret-key"
```

--------------------------------

### Manage macOS Launchd Service Lifecycle

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Commands to load, start, list, and view logs for the installed launchd service.

```shell
sudo launchctl load /Library/LaunchDaemons/com.bluewavelabs.capture.plist
sudo launchctl start com.bluewavelabs.capture
sudo launchctl list | grep com.bluewavelabs.capture
tail -f /var/log/com.bluewavelabs.capture.log
```

--------------------------------

### Example Struct Definition

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/MANIFEST.md

Type definitions are presented as exact code, followed by tables detailing their fields. This example shows a Config struct.

```go
type Config struct {
    Port      string
    APISecret string
}
```

--------------------------------

### Navigate to Output Directory

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/00-START-HERE.md

Change the current directory to the project's output directory to begin setup.

```bash
cd /workspace/home/output
```

--------------------------------

### Install Capture Helm Chart

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/configuration.md

Use this command to install the Capture Helm chart locally, applying your custom configurations from a values.yaml file.

```bash
cd deployment/helm/capture
helm install capture . -f values.yaml

```

--------------------------------

### Run Capture Application

Source: https://github.com/bluewave-labs/capture/blob/develop/CONTRIBUTING.md

Start the Capture application from the command line.

```bash
go run cmd/capture/main.go
```

--------------------------------

### Start Capture Agent

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/README.md

Set the API secret and start the capture agent. The agent will then listen for requests.

```bash
# Set required configuration
export API_SECRET=my-secret-key

# Start the server
./capture

# The agent is now listening on http://localhost:59232

```

--------------------------------

### Start HTTP Server in Background

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/server.md

Starts the HTTP server to listen for incoming requests concurrently in a background goroutine. Panics if the server fails unexpectedly.

```go
srv := server.NewServer(appConfig, nil, metadata)
srv.Serve()
// Server is now listening in the background
```

--------------------------------

### Complete Capture Configuration

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

This example shows a complete configuration for running the Capture binary, including optional port and Gin mode settings.

```shell
API_SECRET=your-secret-key PORT=59232 GIN_MODE=release ./capture
```

--------------------------------

### Integrate Config with main()

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/config.md

Typical usage pattern in cmd/capture/main.go to initialize the application configuration using environment variables and start the server.

```go
func main() {
    appConfig := config.NewConfig(
        os.Getenv("PORT"),
        os.Getenv("API_SECRET"),
    )
    
    srv := server.NewServer(appConfig, nil, &handler.CaptureMeta{
        Version: "1.0.0",
    })
    
    srv.Serve()
    srv.GracefulShutdown(5 * time.Second)
}
```

--------------------------------

### Example: NewConfig Usage

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/config.md

Demonstrates creating a Config with valid parameters, using default port, and the fatal error case when the API secret is missing.

```go
// Valid configuration
config := config.NewConfig("8080", "my-secret-key")
// config.Port = "8080"
// config.APISecret = "my-secret-key"

// Using defaults
config := config.NewConfig("", "another-secret")
// config.Port = "59232" (default)
// config.APISecret = "another-secret"

// Invalid - missing secret (fatal)
config := config.NewConfig("8080", "")
// Terminates with: "API_SECRET environment variable is required for security purposes. Please set it before starting the server."
```

--------------------------------

### Install macOS Launchd Service with API Secret

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Supply the API secret as an argument during the installation script execution.

```shell
curl -fsSL https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/macos/install.sh \
    | sudo bash -s -- --api-secret "your-secret-key"
```

--------------------------------

### Load and Start Manually Configured macOS Launchd Service

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Load the manually placed plist file into launchd and start the service.

```shell
sudo launchctl load /Library/LaunchDaemons/com.bluewavelabs.capture.plist
sudo launchctl start com.bluewavelabs.capture
```

--------------------------------

### Install Linux Systemd Service with API Secret

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Run the installation script and provide the API secret as an argument. This avoids interactive prompts for the secret.

```shell
curl -fsSL https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/linux/install.sh \
    | sudo bash -s -- --api-secret "your-secret-key"
```

--------------------------------

### Install Bluewave Capture Agent on Windows

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Installs the Capture agent as a Windows service. Requires PowerShell 5.1+ and Administrator privileges. The script detects CPU architecture, downloads the latest release, and registers the service.

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
Invoke-RestMethod https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/windows/install.ps1 | Invoke-Expression
```

--------------------------------

### Serve

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/server.md

Starts the HTTP server to listen for incoming requests concurrently using a goroutine.

```APIDOC
## Serve

### Description
Starts the HTTP server to listen for incoming requests concurrently using a goroutine.

### Method Signature
```go
func (s *Server) Serve()
```

### Behavior
- Launches the server in a background goroutine
- Logs the server address upon startup
- Panics with `log.Fatalf` if the server fails unexpectedly

### Example
```go
appConfig := &config.Config{
    Port:      "59232",
    APISecret: "your-secret-key",
}

metadata := &handler.CaptureMeta{
    Version: "1.0.0",
}

srv := server.NewServer(appConfig, nil, metadata)
srv.Serve()
// Server is now listening in the background
```
```

--------------------------------

### Example: Default Config Usage

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/config.md

Shows how to create a Config using the Default() function, resulting in a default port and an empty API secret.

```go
config := config.Default()
// config.Port = "59232"
// config.APISecret = "" (empty - not secure)
```

--------------------------------

### Install Filesystem Tools for Disk Testing

Source: https://github.com/bluewave-labs/capture/blob/develop/docs/TESTING.md

Install optional filesystem tools required for disk metrics filesystem testing on Debian/Ubuntu systems. This includes tools for ext4, xfs, btrfs, zfs, and LVM.

```bash
# Install all optional filesystem tools
sudo apt update && sudo apt install -y e2fsprogs xfsprogs btrfs-progs zfsutils-linux lvm2
```

--------------------------------

### Install Bluewave Capture Agent with API Secret

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Installs the Capture agent and supplies the API secret as a parameter. Ensure PowerShell 5.1+ and Administrator privileges are used.

```powershell
& ([scriptblock]::Create(
    (Invoke-RestMethod https://raw.githubusercontent.com/bluewave-labs/capture/main/deployment/windows/install.ps1)
)) -APISecret "your-secret-key"
```

--------------------------------

### Start Caddy Reverse Proxy with Docker Compose

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Starts the Caddy reverse proxy service in detached mode using Docker Compose. Ensure the Caddyfile and compose file are correctly configured.

```shell
docker compose -f caddy.compose.yml up -d
```

--------------------------------

### Example Function Signature

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/MANIFEST.md

Functions are documented using Go syntax with full type information. This shows the signature format for a NewServer function.

```go
func NewServer(config *config.Config, handler http.Handler, metadata *handler.CaptureMeta) *Server
```

--------------------------------

### Set Up Capture Environment

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/00-START-HERE.md

These commands set the API secret as an environment variable and start the Capture service. The API_SECRET is required for most operations.

```bash
export API_SECRET=your-secret-key
./capture
```

--------------------------------

### API Authentication Header Example

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/config.md

Demonstrates the required format for the Authorization header when making API requests, using a Bearer token.

```bash
Authorization: Bearer your-secret-key
```

--------------------------------

### Deploy Capture Helm Chart

Source: https://github.com/bluewave-labs/capture/blob/develop/deployment/helm/capture/INSTALLATION.md

Install the Capture application using the Helm chart. This command deploys the chart from the current directory.

```shell
helm install capture .
```

--------------------------------

### Example Authorization Header

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/endpoints.md

All /api/v1/** endpoints require the Authorization header with a Bearer token.

```http
Authorization: Bearer your-api-secret
```

--------------------------------

### Get Host Metrics

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/handler.md

Collects and returns host system information. Requires authentication.

```Go
func (h *MetricsHandler) MetricsHost(c *gin.Context)
```

```bash
curl -H "Authorization: Bearer your-secret" \
  http://localhost:59232/api/v1/metrics/host
```

```json
{
  "data": {
    "os": "linux",
    "platform": "x86_64",
    "kernel_version": "6.1.0-13-generic",
    "pretty_name": "Ubuntu 22.04.3 LTS"
  },
  "capture": { "version": "1.0.0", "mode": "release" },
  "errors": null
}
```

--------------------------------

### Copy and Set Permissions for Manual Plist Installation

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Copy the edited plist file to the launchd daemons directory and set the correct ownership and permissions.

```shell
cp deployment/macos/capture.plist /Library/LaunchDaemons/com.bluewavelabs.capture.plist
chown root:wheel /Library/LaunchDaemons/com.bluewavelabs.capture.plist
chmod 644 /Library/LaunchDaemons/com.bluewavelabs.capture.plist
```

--------------------------------

### Get Host Information

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/metrics.md

Collects host operating system and kernel information. Logs the OS, pretty name, and kernel version.

```Go
hostData, hostErrs := metric.GetHostInformation()
log.Printf("OS: %s (%s)", hostData.Os, hostData.PrettyName)
log.Printf("Kernel: %s", hostData.KernelVersion)
```

--------------------------------

### API Request with Missing Authentication

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/endpoints.md

This example shows a request without an Authorization header, which will result in a 401 Unauthorized error.

```bash
curl http://localhost:59232/api/v1/metrics
# Response: 401 Unauthorized
# {"error":"Unable to parse 'Authorization' header"}
```

--------------------------------

### Run Benchmarking Tests

Source: https://github.com/bluewave-labs/capture/blob/develop/docs/TESTING.md

Execute benchmarking tests and save the results to a file. Use this command to get a baseline performance measurement.

```bash
go test -benchmem -run='^$'
    -bench . 
    -count 10 
    ./test/benchmark | tee my_benchmark_result.txt
```

--------------------------------

### Curl Example for Empty Authorization Token

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/errors.md

Demonstrates how to trigger the 'Unauthorized' error with an empty token using a curl command.

```bash
curl -H "Authorization: Bearer " http://localhost:59232/api/v1/metrics
```

--------------------------------

### Get All System Metrics

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/endpoints.md

Retrieve aggregated system metrics. Requires Bearer token authentication.

```bash
curl -H "Authorization: Bearer my-secret-key" \
  http://localhost:59232/api/v1/metrics
```

--------------------------------

### Manage Linux Systemd Service

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Use systemctl commands to manage the installed Bluewave Capture service. This includes checking status, starting, stopping, and restarting the service, as well as viewing logs.

```shell
systemctl status capture
systemctl stop capture
systemctl start capture
systemctl restart capture
journalctl -u capture -f
```

--------------------------------

### Get NVMe Drive SMART Metrics

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/metrics.md

Collects S.M.A.R.T. data from NVMe drives. Requires the 'smartctl' binary to be installed and in the system's PATH. May require root privileges for full data.

```go
func GetSmartMetrics() (SmartData, []CustomErr)
```

```go
smartData, smartErrs := metric.GetSmartMetrics()
if len(smartErrs) > 0 {
    log.Printf("SMART collection warnings: %v", smartErrs)
}
log.Printf("Drive Temperature: %s°C", smartData.Temperature)
log.Printf("Health: %s", smartData.SmartOverallHealthResult)
```

--------------------------------

### Run Capture with Custom Port

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/configuration.md

Starts the capture application with a custom port specified by the PORT environment variable. The API_SECRET must also be set.

```bash
export API_SECRET=my-secret-key
export PORT=8080
./capture
```

--------------------------------

### Get NVMe Drive SMART Health Metrics

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/endpoints.md

Retrieves S.M.A.R.T. health data for NVMe drives. Requires the `smartctl` binary to be installed and may need root privileges. Ensure a valid Bearer token is provided in the Authorization header.

```bash
curl -H "Authorization: Bearer my-secret-key" \
  http://localhost:59232/api/v1/metrics/smart
```

--------------------------------

### Curl Examples for Missing or Malformed Authorization Header

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/errors.md

Demonstrates how to trigger the 'Unauthorized' error using curl commands with a missing or malformed 'Authorization' header.

```bash
# Missing header
curl http://localhost:59232/api/v1/metrics

# Malformed header
curl -H "Authorization: Basic abc123" http://localhost:59232/api/v1/metrics
```

--------------------------------

### Create New Server Instance

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/server.md

Use this function to create and configure a new HTTP server. It requires configuration, an optional handler, and metadata.

```go
appConfig := &config.Config{
    Port:      "59232",
    APISecret: "your-secret-key",
}

metadata := &handler.CaptureMeta{
    Version: "1.0.0",
}

srv := server.NewServer(appConfig, nil, metadata)
```

--------------------------------

### Implement Fallback for Critical Metrics

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/errors.md

This example demonstrates how to implement a fallback mechanism for critical metrics, such as CPU temperature. If the primary data is unavailable (nil), it logs a warning and uses a predefined fallback value.

```go
if cpuData.Temperature == nil {
    log.Warn("CPU temperature unavailable, using fallback")
    cpuData.Temperature = fallbackTemperature()
}
```

--------------------------------

### Manage Capture Windows Service

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Standard PowerShell cmdlets to manage the installed Capture Windows service. Use these after the agent has been successfully installed.

```powershell
Get-Service capture
Stop-Service capture
Start-Service capture
Restart-Service capture
```

--------------------------------

### Environment Variables for Server Configuration

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/server.md

Demonstrates how to set server configuration parameters using environment variables. Ensure API_SECRET is set for authentication.

```bash
export PORT=59232
export API_SECRET=your-secret-key
```

--------------------------------

### Run Capture with Minimal Configuration

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/configuration.md

Starts the capture application with a required API secret and default port. The server listens on 0.0.0.0:59232 and requires a specific Authorization header.

```bash
export API_SECRET=my-secret-key
./capture
```

--------------------------------

### Initialize HTTP Handler with Routes

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/server.md

Initializes a new HTTP handler with all necessary routes and middleware. It requires configuration and metadata.

```go
config := &config.Config{
    Port:      "59232",
    APISecret: "my-secret-key",
}

metadata := &handler.CaptureMeta{
    Version: "1.0.0",
}

handler := server.InitializeHandler(config, metadata)
httpServer := &http.Server{
    Addr:    "0.0.0.0:59232",
    Handler: handler,
}
```

--------------------------------

### Initialize Application Configuration

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/configuration.md

Initializes the application configuration by reading environment variables for PORT and API_SECRET. If PORT is empty, a default value is used. If API_SECRET is empty, the application terminates.

```go
appConfig := config.NewConfig(
    os.Getenv("PORT"),
    os.Getenv("API_SECRET"),
)
```

--------------------------------

### Build Capture from Source

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Clone the repository and build the Capture binary from source code. This method provides the most flexibility for development.

```shell
git clone git@github.com:bluewave-labs/capture
cd capture
just build   # or: go build -o dist/capture ./cmd/capture/
```

--------------------------------

### GET /api/v1/metrics/net

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Interface-level network throughput.

```APIDOC
## GET /api/v1/metrics/net

### Description
Interface-level network throughput.

### Method
GET

### Endpoint
/api/v1/metrics/net

### Parameters

### Request Example

### Response
#### Success Response (200)
- **data** (object) - network metrics payload
- **capture** (object) - capture metadata
- **errors** (array) - optional array of error messages if any collectors failed, can be null

#### Response Example
```json
{
  "data": {},
  "capture": {
    "version": "1.0.0",
    "mode": "release"
  },
  "errors": null
}
```
```

--------------------------------

### NewServer

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/server.md

Creates and configures a new HTTP server instance with specified configuration, handler, and metadata.

```APIDOC
## NewServer

### Description
Creates and configures a new HTTP server instance.

### Function Signature
```go
func NewServer(config *config.Config, handler http.Handler, metadata *handler.CaptureMeta) *Server
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **config** (`*config.Config`) - Required - Server configuration including port and API secret
- **handler** (`http.Handler`) - Optional - HTTP request handler; if nil, InitializeHandler is used
- **metadata** (`*handler.CaptureMeta`) - Required - Metadata for API responses (version, mode)

### Request Example
```go
appConfig := &config.Config{
    Port:      "59232",
    APISecret: "your-secret-key",
}

metadata := &handler.CaptureMeta{
    Version: "1.0.0",
}

srv := server.NewServer(appConfig, nil, metadata)
```

### Response
#### Success Response
- **`*Server`**: A configured HTTP server ready to serve requests
```

--------------------------------

### GET /api/v1/metrics/smart

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

S.M.A.R.T. drive health information.

```APIDOC
## GET /api/v1/metrics/smart

### Description
S.M.A.R.T. drive health information.

### Method
GET

### Endpoint
/api/v1/metrics/smart

### Parameters

### Request Example

### Response
#### Success Response (200)
- **data** (object) - S.M.A.R.T. data payload
- **capture** (object) - capture metadata
- **errors** (array) - optional array of error messages if any collectors failed, can be null

#### Response Example
```json
{
  "data": {},
  "capture": {
    "version": "1.0.0",
    "mode": "release"
  },
  "errors": null
}
```
```

--------------------------------

### GET /api/v1/metrics/memory

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Memory totals and usage metrics.

```APIDOC
## GET /api/v1/metrics/memory

### Description
Memory totals and usage metrics.

### Method
GET

### Endpoint
/api/v1/metrics/memory

### Parameters

### Request Example

### Response
#### Success Response (200)
- **data** (object) - memory metrics payload
- **capture** (object) - capture metadata
- **errors** (array) - optional array of error messages if any collectors failed, can be null

#### Response Example
```json
{
  "data": {},
  "capture": {
    "version": "1.0.0",
    "mode": "release"
  },
  "errors": null
}
```
```

--------------------------------

### GET /api/v1/metrics/cpu

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

CPU temps, load, and utilization.

```APIDOC
## GET /api/v1/metrics/cpu

### Description
CPU temps, load, and utilization.

### Method
GET

### Endpoint
/api/v1/metrics/cpu

### Parameters

### Request Example

### Response
#### Success Response (200)
- **data** (object) - CPU metrics payload
- **capture** (object) - capture metadata
- **errors** (array) - optional array of error messages if any collectors failed, can be null

#### Response Example
```json
{
  "data": {},
  "capture": {
    "version": "1.0.0",
    "mode": "release"
  },
  "errors": null
}
```
```

--------------------------------

### InitializeHandler

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/server.md

Creates and configures all routes with middleware for the Capture API.

```APIDOC
## InitializeHandler

### Description
Creates and configures all routes with middleware for the Capture API.

### Function Signature
```go
func InitializeHandler(config *config.Config, metadata *handler.CaptureMeta) http.Handler
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **config** (`*config.Config`) - Required - Configuration containing API secret for authentication
- **metadata** (`*handler.CaptureMeta`) - Required - Metadata to include in API responses

### Response
#### Success Response
- **`http.Handler`**: A configured HTTP handler with all routes and middleware

### Routes Registered
- `GET /health` — Public health check endpoint (no authentication required)
- `GET /api/v1/metrics` — All system metrics (authenticated)
- `GET /api/v1/metrics/cpu` — CPU metrics only (authenticated)
- `GET /api/v1/metrics/memory` — Memory metrics only (authenticated)
- `GET /api/v1/metrics/disk` — Disk metrics only (authenticated)
- `GET /api/v1/metrics/host` — Host information only (authenticated)
- `GET /api/v1/metrics/smart` — S.M.A.R.T. drive data (authenticated)
- `GET /api/v1/metrics/net` — Network interface stats (authenticated)
- `GET /api/v1/metrics/docker` — Docker container metrics (authenticated)

### Request Example
```go
config := &config.Config{
    Port:      "59232",
    APISecret: "my-secret-key",
}

metadata := &handler.CaptureMeta{
    Version: "1.0.0",
}

handler := server.InitializeHandler(config, metadata)
httpServer := &http.Server{
    Addr:    "0.0.0.0:59232",
    Handler: handler,
}
```
```

--------------------------------

### Get Network Metrics

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/README.md

Retrieves network interface statistics.

```APIDOC
## GET /api/v1/metrics/net

### Description
Retrieves network interface statistics.

### Method
GET

### Endpoint
/api/v1/metrics/net

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **NetData[]** (array) - Array of network interface statistics.
```

--------------------------------

### GET /api/v1/metrics/host

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Host metadata (OS, uptime, kernel, etc.).

```APIDOC
## GET /api/v1/metrics/host

### Description
Host metadata (OS, uptime, kernel, etc.).

### Method
GET

### Endpoint
/api/v1/metrics/host

### Parameters

### Request Example

### Response
#### Success Response (200)
- **data** (object) - host metadata payload
- **capture** (object) - capture metadata
- **errors** (array) - optional array of error messages if any collectors failed, can be null

#### Response Example
```json
{
  "data": {},
  "capture": {
    "version": "1.0.0",
    "mode": "release"
  },
  "errors": null
}
```
```

--------------------------------

### GET /api/v1/metrics/disk

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Disk capacity, inode usage, and IO stats.

```APIDOC
## GET /api/v1/metrics/disk

### Description
Disk capacity, inode usage, and IO stats.

### Method
GET

### Endpoint
/api/v1/metrics/disk

### Parameters

### Request Example

### Response
#### Success Response (200)
- **data** (object) - disk metrics payload
- **capture** (object) - capture metadata
- **errors** (array) - optional array of error messages if any collectors failed, can be null

#### Response Example
```json
{
  "data": {},
  "capture": {
    "version": "1.0.0",
    "mode": "release"
  },
  "errors": null
}
```
```

--------------------------------

### Get Memory Metrics

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/README.md

Retrieves detailed memory usage metrics.

```APIDOC
## GET /api/v1/metrics/memory

### Description
Retrieves detailed memory usage metrics.

### Method
GET

### Endpoint
/api/v1/metrics/memory

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **MemoryData** (object) - Memory usage data.
```

--------------------------------

### Display Capture Version Information

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/configuration.md

Use the -version or --version flag to display build information including version, commit hash, and compilation date. This command will exit after displaying the information.

```bash
./capture -version
```

```bash
./capture --version
```

--------------------------------

### Get CPU Metrics

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/README.md

Retrieves detailed CPU utilization metrics.

```APIDOC
## GET /api/v1/metrics/cpu

### Description
Retrieves detailed CPU utilization metrics.

### Method
GET

### Endpoint
/api/v1/metrics/cpu

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **CPUData** (object) - CPU utilization data.
```

--------------------------------

### GET /api/v1/metrics/docker

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/MANIFEST.md

Retrieves Docker container metrics. This endpoint requires authentication.

```APIDOC
## GET /api/v1/metrics/docker

### Description
Retrieves Docker container metrics. This endpoint requires authentication.

### Method
GET

### Endpoint
/api/v1/metrics/docker

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **totalContainers** (integer) - The total number of Docker containers.
- **runningContainers** (integer) - The number of running Docker containers.
- **stoppedContainers** (integer) - The number of stopped Docker containers.

#### Response Example
{
  "totalContainers": 5,
  "runningContainers": 3,
  "stoppedContainers": 2
}
```

--------------------------------

### GET /api/v1/metrics/net

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/MANIFEST.md

Retrieves network interface statistics. This endpoint requires authentication.

```APIDOC
## GET /api/v1/metrics/net

### Description
Retrieves network interface statistics. This endpoint requires authentication.

### Method
GET

### Endpoint
/api/v1/metrics/net

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **bytesSent** (integer) - Total bytes sent over the network.
- **bytesReceived** (integer) - Total bytes received over the network.

#### Response Example
{
  "bytesSent": 1024,
  "bytesReceived": 2048
}
```

--------------------------------

### Example API Response JSON

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/handler.md

Illustrates the structure of a typical JSON response from a metric endpoint, showing sample data for CPU metrics, agent metadata, and no errors.

```json
{
  "data": {
    "physical_core": 4,
    "logical_core": 8,
    "frequency": 3600.0,
    "current_frequency": 3200,
    "temperature": [45.5, 46.2, 45.8, 46.1],
    "free_percent": 0.7,
    "usage_percent": 0.3
  },
  "capture": {
    "version": "1.0.0",
    "mode": "release"
  },
  "errors": null
}
```

--------------------------------

### GET /api/v1/metrics/host

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/MANIFEST.md

Retrieves host system information. This endpoint requires authentication.

```APIDOC
## GET /api/v1/metrics/host

### Description
Retrieves host system information. This endpoint requires authentication.

### Method
GET

### Endpoint
/api/v1/metrics/host

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **hostname** (string) - The hostname of the system.
- **os** (string) - The operating system name.
- **platform** (string) - The system architecture.

#### Response Example
{
  "hostname": "example-host",
  "os": "linux",
  "platform": "x86_64"
}
```

--------------------------------

### GET /api/v1/metrics/disk

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/MANIFEST.md

Retrieves disk utilization metrics. This endpoint requires authentication.

```APIDOC
## GET /api/v1/metrics/disk

### Description
Retrieves disk utilization metrics. This endpoint requires authentication.

### Method
GET

### Endpoint
/api/v1/metrics/disk

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **total** (integer) - Total disk size in bytes.
- **used** (integer) - Used disk space in bytes.
- **free** (integer) - Free disk space in bytes.

#### Response Example
{
  "total": 1000000000,
  "used": 500000000,
  "free": 500000000
}
```

--------------------------------

### Get All System Metrics

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/metrics.md

Aggregates all available system metrics, including CPU, memory, disk, host, and network data, into a single structure. Use this for a comprehensive system overview.

```go
func GetAllSystemMetrics() (AllMetrics, []CustomErr)
```

```go
allMetrics, allErrs := metric.GetAllSystemMetrics()
if len(allErrs) > 0 {
    log.Printf("Some collectors failed: %v", allErrs)
}
// Process allMetrics
```

--------------------------------

### GET /api/v1/metrics/memory

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/MANIFEST.md

Retrieves memory utilization metrics. This endpoint requires authentication.

```APIDOC
## GET /api/v1/metrics/memory

### Description
Retrieves memory utilization metrics. This endpoint requires authentication.

### Method
GET

### Endpoint
/api/v1/metrics/memory

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **total** (integer) - Total system memory in bytes.
- **used** (integer) - Used system memory in bytes.
- **free** (integer) - Free system memory in bytes.

#### Response Example
{
  "total": 16777216,
  "used": 8388608,
  "free": 8388608
}
```

--------------------------------

### Fetch Metrics with Go Client

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/README.md

This Go program demonstrates how to retrieve system metrics from the Capture API. Ensure the API response structure matches the defined Go structs.

```go
package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

type APIResponse struct {
    Data struct {
        CPU struct {
            UsagePercent float64 `json:"usage_percent"`
        } `json:"cpu"`
    } `json:"data"`
}

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "http://localhost:59232/api/v1/metrics", nil)
    req.Header.Add("Authorization", "Bearer my-secret-key")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    
    var data APIResponse
    json.NewDecoder(resp.Body).Decode(&data)
    
    fmt.Printf("CPU Usage: %.2f%%\n", data.Data.CPU.UsagePercent * 100)
}
```

--------------------------------

### GET /api/v1/metrics/cpu

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/MANIFEST.md

Retrieves CPU utilization metrics. This endpoint requires authentication.

```APIDOC
## GET /api/v1/metrics/cpu

### Description
Retrieves CPU utilization metrics. This endpoint requires authentication.

### Method
GET

### Endpoint
/api/v1/metrics/cpu

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **user** (float) - CPU time spent in user mode.
- **system** (float) - CPU time spent in system mode.
- **idle** (float) - CPU time spent in idle mode.

#### Response Example
{
  "user": 0.1,
  "system": 0.2,
  "idle": 99.7
}
```

--------------------------------

### GET /api/v1/metrics

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/MANIFEST.md

Retrieves a comprehensive set of metrics. This endpoint requires authentication.

```APIDOC
## GET /api/v1/metrics

### Description
Retrieves a comprehensive set of metrics. This endpoint requires authentication.

### Method
GET

### Endpoint
/api/v1/metrics

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **cpu** (CPUData) - CPU utilization metrics.
- **memory** (MemoryData) - Memory utilization metrics.
- **disk** (DiskData) - Disk utilization metrics.
- **host** (HostData) - Host system information.
- **net** (NetData) - Network interface statistics.
- **smart** (SmartData) - SMART disk health data.
- **docker** (DockerMetrics) - Docker container metrics.

#### Response Example
{
  "cpu": {
    "user": 0.1,
    "system": 0.2,
    "idle": 99.7
  },
  "memory": {
    "total": 16777216,
    "used": 8388608,
    "free": 8388608
  },
  "disk": {
    "total": 1000000000,
    "used": 500000000,
    "free": 500000000
  },
  "host": {
    "hostname": "example-host",
    "os": "linux",
    "platform": "x86_64"
  },
  "net": {
    "bytesSent": 1024,
    "bytesReceived": 2048
  },
  "smart": {
    "modelName": "SSD Model",
    "serialNumber": "SN12345",
    "powerOnHours": 1000,
    "temperature": 45
  },
  "docker": {
    "totalContainers": 5,
    "runningContainers": 3,
    "stoppedContainers": 2
  }
}
```

--------------------------------

### GET /health

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/MANIFEST.md

Retrieves the health status of the Capture API. This is a public endpoint.

```APIDOC
## GET /health

### Description
Retrieves the health status of the Capture API. This is a public endpoint.

### Method
GET

### Endpoint
/health

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status of the service.

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### Create Default Config

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/config.md

Creates a Config instance with default values. Note that the default configuration has an empty API secret and is not suitable for production.

```go
func Default() *Config
```

--------------------------------

### Create New Config Instance

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/config.md

Creates a new Config instance, applying validation and defaults. It enforces the API secret requirement and uses a default port if none is provided.

```go
func NewConfig(port string, apiSecret string) *Config
```

--------------------------------

### GET /api/v1/metrics/docker

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Docker container metrics. Use `?all=true` to include stopped containers.

```APIDOC
## GET /api/v1/metrics/docker

### Description
Docker container metrics. Use `?all=true` to include stopped containers.

### Method
GET

### Endpoint
/api/v1/metrics/docker

### Parameters
#### Query Parameters
- **all** (boolean) - Optional - Use `true` to include stopped containers.

### Request Example

### Response
#### Success Response (200)
- **data** (object) - Docker metrics payload
- **capture** (object) - capture metadata
- **errors** (array) - optional array of error messages if any collectors failed, can be null

#### Response Example
```json
{
  "data": {},
  "capture": {
    "version": "1.0.0",
    "mode": "release"
  },
  "errors": null
}
```
```

--------------------------------

### Get Disk Metrics

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/README.md

Retrieves detailed disk I/O statistics for all attached disks.

```APIDOC
## GET /api/v1/metrics/disk

### Description
Retrieves detailed disk I/O statistics for all attached disks.

### Method
GET

### Endpoint
/api/v1/metrics/disk

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **DiskData[]** (array) - Array of disk I/O statistics.
```

--------------------------------

### GET /health

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/endpoints.md

Public health check endpoint for liveness probes. Does not require authentication.

```APIDOC
## GET /health

### Description
Public health check endpoint for liveness probes. Does not require authentication.

### Method
GET

### Endpoint
/health

### Parameters
#### Query Parameters
None

### Response
#### Success Response (200)
- **Response Body**: "OK"

### Response Example
```json
"OK"
```
```

--------------------------------

### Fetch All Metrics

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/README.md

Use curl to fetch all available metrics from the agent. Ensure you include your API secret in the Authorization header.

```bash
curl -H "Authorization: Bearer my-secret-key" \
  http://localhost:59232/api/v1/metrics

```

--------------------------------

### Get SMART Metrics

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/README.md

Retrieves Self-Monitoring, Analysis and Reporting Technology (SMART) data for disks.

```APIDOC
## GET /api/v1/metrics/smart

### Description
Retrieves Self-Monitoring, Analysis and Reporting Technology (SMART) data for disks.

### Method
GET

### Endpoint
/api/v1/metrics/smart

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **SmartData** (object) - SMART data for disks.
```

--------------------------------

### Metrics

Source: https://github.com/bluewave-labs/capture/blob/develop/_autodocs/api-reference/handler.md

Collects and returns all available system metrics.

```APIDOC
## Metrics

Collects and returns all available system metrics.

```go
func (h *MetricsHandler) Metrics(c *gin.Context)
```

**Path:** `GET /api/v1/metrics`  
**Auth:** Required (Bearer token)

**Response Body:**

An `APIResponse` with `data` field containing an `AllMetrics` object with CPU, memory, disk, host, and network data.

**Status Codes:**

- `200 OK` — All metrics collected successfully
- `207 Multi-Status` — Some metrics failed; details in `errors` array

**Example:**

```bash
curl -H "Authorization: Bearer your-secret" \
  http://localhost:59232/api/v1/metrics
```

**Response:**

```json
{
  "data": {
    "cpu": { "physical_core": 4, "logical_core": 8, ... },
    "memory": { "total_bytes": 17179869184, ... },
    "disk": [ { "device": "/dev/sda1", ... } ],
    "host": { "os": "linux", ... },
    "net": [ { "name": "eth0", ... } ]
  },
  "capture": { "version": "1.0.0", "mode": "release" },
  "errors": null
}
```
```

--------------------------------

### GET /health

Source: https://github.com/bluewave-labs/capture/blob/develop/README.md

Liveness probe that returns "OK". Useful for container orchestrators.

```APIDOC
## GET /health

### Description
Liveness probe that returns "OK". Useful for container orchestrators.

### Method
GET

### Endpoint
/health

### Parameters

### Request Example

### Response
#### Success Response (200)
- **status** (string) - "OK"

#### Response Example
```json
"OK"
```
```