LogLynx Widget Guide

This guide explains how to use LogLynx widgets to embed compact analytics in dashboards like Homarr, Home Assistant, or any other platform that supports iframes.

Table of Contents

• Overview
• Enabling/Disabling Widgets
• Widget Page
• Widget API Endpoints
• Integration Examples
• Troubleshooting

---

Overview

LogLynx provides a compact widget page and API endpoints designed for embedding in external dashboards. The widget shows essential metrics at a glance:

• Requests/min or Total Requests (depending on mode)
• Error Rate (4xx + 5xx percentage)
• Average Response Time
• Unique IPs
• Traffic Sparkline Chart

Two Modes Available

Mode	URL Parameter	Description	Refresh Rate
Realtime	(default)	Live metrics from last hour	5 seconds
Summary	?time=1h, ?time=24h, ?time=7d, ?time=30d	Aggregated data for time period	60 seconds

---

Enabling/Disabling Widgets

Environment Variable

Widgets are disabled by default. To enable them, set in your .env file:

# Enable widget page and API endpoints
WIDGET_ENABLED=true

What Gets Disabled

When WIDGET_ENABLED=false:

Endpoint	Status
/widget (page)	404 Not Found
/api/v1/widget/data	404 Not Found
/api/v1/widget/summary	404 Not Found
/api/v1/widget/timeline	404 Not Found

Server Log

When widgets are disabled, you'll see this log message at startup:

Widget endpoints disabled

---

Widget Page

URL Format

http://YOUR-LOGLYNX-HOST:8080/widget?theme=dark&time=24h

Query Parameters

Parameter	Values	Default	Description
theme	dark, light	dark	Color theme
time	realtime, 1h, 24h, 7d, 30d	realtime	Time period for data

Examples

Realtime Widget (Default)

http://localhost:8080/widget
http://localhost:8080/widget?theme=dark

Shows live metrics updating every 5 seconds.

Today's Summary

http://localhost:8080/widget?time=24h&theme=dark

Shows aggregated data for the last 24 hours.

Weekly Summary

http://localhost:8080/widget?time=7d&theme=light

Shows aggregated data for the last 7 days with light theme.

Monthly Summary

http://localhost:8080/widget?time=30d

Shows aggregated data for the last 30 days.

Displayed Metrics

Realtime Mode

Metric	Description
Status	System health (Healthy/Warning/Critical/Error)
Requests/min	Current requests per minute
Error Rate	Combined 4xx + 5xx percentage
Avg Response	Average response time in ms
Unique IPs	Unique IP addresses in last hour
Sparkline	Traffic chart (last 30 data points)

Summary Mode (?time=...)

Metric	Description
Status	System health for the period
Total Requests	Total requests in the time period
Error Rate	Combined 4xx + 5xx percentage
Avg Response	Average response time in ms
Unique IPs	Unique IP addresses in the period
Sparkline	Traffic chart for the period

---

Widget API Endpoints

For custom integrations, use the REST API endpoints directly.

GET /api/v1/widget/data

Returns real-time metrics from the last hour.

Response:

{
  "status": "healthy",
  "requests_per_minute": 125.5,
  "error_rate": 2.5,
  "avg_response_time": 145.3,
  "unique_ips": 1523
}

Fields:

Field	Type	Description
status	string	healthy, warning, danger, or error
requests_per_minute	number	Requests per minute
error_rate	number	Error percentage (0-100)
avg_response_time	number	Average response time in ms
unique_ips	integer	Unique IPs in last hour

---

GET /api/v1/widget/summary

Returns aggregated statistics for a time period.

Parameters:

Name	Type	Default	Description
hours	integer	24	Hours to analyze (1-720)

Example Request:

GET /api/v1/widget/summary?hours=168

Response:

{
  "status": "healthy",
  "total_requests": 125643,
  "requests_per_hr": 743.5,
  "error_rate": 2.5,
  "avg_response_ms": 145.3,
  "unique_ips": 15234,
  "bandwidth_mb": 5123.5
}

---

GET /api/v1/widget/timeline

Returns timeline data for sparkline charts.

Parameters:

Name	Type	Default	Description
hours	integer	24	Hours to analyze (1-720)

Example Request:

GET /api/v1/widget/timeline?hours=24

Response:

[
  { "hour": "2025-11-03T10:00:00Z", "requests": 1523 },
  { "hour": "2025-11-03T11:00:00Z", "requests": 1845 },
  { "hour": "2025-11-03T12:00:00Z", "requests": 2103 }
]

Notes:

• Returns up to 30 points for periods ≤ 24 hours
• Returns up to 50 points for longer periods

---

Integration Examples

Homarr

1. Add an iFrame widget to your board
2. Configure with these settings:

Setting	Value
Embed URL	http://YOUR-LOGLYNX:8080/widget?theme=dark
Allow scrolling	No
Allow full screen	No

Recommended Dimensions:

• Width: 2 columns
• Height: 3-4 rows

Different Time Periods:

# Realtime
http://YOUR-LOGLYNX:8080/widget?theme=dark

# Today
http://YOUR-LOGLYNX:8080/widget?time=24h&theme=dark

# This Week
http://YOUR-LOGLYNX:8080/widget?time=7d&theme=dark

Home Assistant

Use the panel_iframe integration:

# configuration.yaml
panel_iframe:
  loglynx:
    title: 'LogLynx Stats'
    url: 'http://YOUR-LOGLYNX:8080/widget?theme=dark'
    icon: mdi:chart-line

Custom HTML/JavaScript

<!DOCTYPE html>
<html>
<head>
    <title>LogLynx Widget</title>
    <style>
        iframe {
            border: none;
            width: 400px;
            height: 350px;
        }
    </style>
</head>
<body>
    <iframe src="http://localhost:8080/widget?theme=dark&time=24h"></iframe>
</body>
</html>

Fetch API Example

// Fetch realtime data
async function getWidgetData() {
    const response = await fetch('http://localhost:8080/api/v1/widget/data');
    const data = await response.json();
    
    console.log('Status:', data.status);
    console.log('Requests/min:', data.requests_per_minute);
    console.log('Error Rate:', data.error_rate + '%');
    console.log('Avg Response:', data.avg_response_time + 'ms');
}

// Fetch weekly summary
async function getWeeklySummary() {
    const response = await fetch('http://localhost:8080/api/v1/widget/summary?hours=168');
    const data = await response.json();
    
    console.log('Total Requests:', data.total_requests);
    console.log('Unique IPs:', data.unique_ips);
}

getWidgetData();
getWeeklySummary();

---

Troubleshooting

Widget Shows "Error" Status

Possible causes:

1. No data in the selected time period
2. Database connection issue
3. Widget endpoints disabled

Solution:

1. Check if LogLynx is receiving logs
2. Check server logs for errors
3. Verify WIDGET_ENABLED=true in .env

Widget Shows "Critical" Status

This means the error rate is above 5%. Check:

1. Backend service health
2. Error logs in LogLynx dashboard
3. Recent traffic patterns

Widget Not Loading (404)

Cause: Widget endpoints are disabled

Solution: Enable in .env:

WIDGET_ENABLED=true

Then restart LogLynx.

Theme Not Applying

Make sure you're using the correct query parameter:

• ✅ ?theme=dark
• ✅ ?theme=light
• ❌ ?theme=black (not supported)

CORS Errors

If embedding from a different domain, ensure your reverse proxy or browser allows iframe embedding. You may need to configure:

Nginx:

add_header X-Frame-Options "ALLOW-FROM https://your-homarr-domain.com";
add_header Content-Security-Policy "frame-ancestors 'self' https://your-homarr-domain.com";

Traefik:

# docker-compose.yml labels
- "traefik.http.middlewares.loglynx-headers.headers.customFrameOptionsValue=ALLOW-FROM https://your-homarr-domain.com"
- "traefik.http.middlewares.loglynx-headers.headers.contentSecurityPolicy=frame-ancestors 'self' https://your-homarr-domain.com"

---

Status Indicators

Status	Color	Meaning
Healthy	Green	Error rate ≤ 1%
Warning	Yellow	Error rate > 1% and ≤ 5%
Critical	Red	Error rate > 5%
Error	Red	API or system error

---

Security Considerations

1. No Authentication: Widget endpoints do not require authentication by default. Consider:

   • Using WIDGET_ENABLED=false on public instances
   • Placing behind a reverse proxy with authentication
   • Using network-level access controls

2. CORS: Widget page allows embedding from any origin. Restrict if needed via reverse proxy configuration.

3. Data Exposure: Widget shows aggregate statistics only, no sensitive data like IP addresses or request details.