Skip to content

API Documentation

Jump to bottom
Kolin edited this page Jun 12, 2026 · 6 revisions

API Documentation

LogLynx provides a comprehensive REST API for programmatic access to all analytics. All endpoints return JSON responses and support optional filtering parameters.

Base URL: http://localhost:8080/api/v1

Authentication: Currently, all endpoints are public (no authentication required)

CORS: Enabled for all origins

Table of Contents

Health Check

GET /health

Check if the server is running and responsive.

Request:

curl http://localhost:8080/health

Response:

{
  "status": "healthy",
  "timestamp": "2025-11-04T10:30:00Z",
  "version":"1.0.0"
}

Service Filtering

Most endpoints support advanced service-based filtering to help you analyze specific services, backends, or hosts.

Service Types

LogLynx intelligently identifies services using three types (in priority order):

  1. backend_name - Traefik backend name (highest priority)
  2. backend_url - Backend URL
  3. host - HTTP Host header (lowest priority)

Single Service Filtering

Filter by a single service using these parameters:

Parameter Type Default Description
service string - Service name to filter by
service_type enum auto Type of service identifier: auto, backend_name, backend_url, or host
host string - Legacy parameter - Equivalent to service with service_type=auto

Examples:

# Auto-detect service type (default)
curl "http://localhost:8080/api/v1/stats/summary?service=api-service"

# Filter specifically by backend name
curl "http://localhost:8080/api/v1/stats/summary?service=api-service&service_type=backend_name"

# Filter by host header
curl "http://localhost:8080/api/v1/stats/summary?service=api.example.com&service_type=host"

# Legacy host parameter (backward compatible)
curl "http://localhost:8080/api/v1/stats/summary?host=api-service"

Multi-Service Filtering

Filter across multiple services simultaneously using array parameters:

Parameter Type Description
services[] string[] Array of service names (can be repeated)
service_types[] enum[] Corresponding array of service types (must match length of services[])

Example:

# Filter for two services with different types
curl "http://localhost:8080/api/v1/stats/summary?services[]=api-service&service_types[]=backend_name&services[]=web.example.com&service_types[]=host"

# Filter multiple backends
curl "http://localhost:8080/api/v1/stats/timeline?services[]=api-prod&service_types[]=backend_name&services[]=api-staging&service_types[]=backend_name&hours=24"

Service Discovery

Use the /services endpoint to discover available services:

curl http://localhost:8080/api/v1/services

Response:

[
  {
    "name": "api-service-prod",
    "type": "backend_name",
    "count": 45632
  },
  {
    "name": "http://api:8080",
    "type": "backend_url",
    "count": 23451
  },
  {
    "name": "web.example.com",
    "type": "host",
    "count": 12345
  }
]

Hide My Traffic

Endpoints that return request data support excluding your own IP address and additional manually specified IPs from results.

Parameters

Parameter Type Default Description
exclude_own_ip boolean false Set to true to exclude requests from your detected IP
excluded_ips[] string[] - Additional IP addresses to exclude manually (can be combined with exclude_own_ip)
exclude_services[] string[] - Optional: Service names to exclude the IPs from (if omitted, excludes from ALL services)
exclude_service_types[] enum[] - Corresponding service types for exclude_services[]

Examples

Hide my traffic from all services:

curl "http://localhost:8080/api/v1/stats/summary?exclude_own_ip=true"

Hide my traffic and additional IPs:

curl "http://localhost:8080/api/v1/stats/summary?exclude_own_ip=true&excluded_ips[]=10.0.0.5&excluded_ips[]=10.0.0.6"

Hide my traffic only on specific services:

curl "http://localhost:8080/api/v1/requests/recent?exclude_own_ip=true&exclude_services[]=admin-panel&exclude_service_types[]=backend_name"

Combine with service filtering:

curl "http://localhost:8080/api/v1/stats/summary?service=api-service&service_type=backend_name&exclude_own_ip=true"

How It Works

  • The server automatically detects your IP address from the request
  • excluded_ips[] lets you manually specify extra IPs to exclude in addition to your own
  • When filtering is active:
    • Without exclude_services[]: All listed IPs are excluded from all services
    • With exclude_services[]: All listed IPs are excluded only from the specified services
  • Perfect for getting accurate analytics when testing or administering your services

Summary Statistics

GET /api/v1/stats/summary

Returns overall statistics including total requests, unique visitors, bandwidth, and success rates.

Query Parameters:

  • service (optional, string) - Service name to filter by
  • service_type (optional, enum: auto, backend_name, backend_url, host) - Type of service identifier (default: auto)
  • services[] (optional, string[]) - Array of service names for multi-service filtering
  • service_types[] (optional, enum[]) - Corresponding array of service types
  • host (optional, string) - Legacy parameter - Equivalent to service with service_type=auto
  • exclude_own_ip (optional, boolean) - Exclude requests from your IP (default: false)
  • exclude_services[] (optional, string[]) - Services to exclude your IP from (used with exclude_own_ip=true)
  • exclude_service_types[] (optional, enum[]) - Service types for exclude_services[]

Request:

# Basic summary
curl http://localhost:8080/api/v1/stats/summary

# Filter by single service
curl "http://localhost:8080/api/v1/stats/summary?service=api-service&service_type=backend_name"

# Filter by multiple services
curl "http://localhost:8080/api/v1/stats/summary?services[]=api-prod&service_types[]=backend_name&services[]=api-staging&service_types[]=backend_name"

# Exclude your own traffic
curl "http://localhost:8080/api/v1/stats/summary?exclude_own_ip=true"

# Legacy host parameter (backward compatible)
curl "http://localhost:8080/api/v1/stats/summary?host=my-service"

Response:

{
  "totalRequests": 125487,
  "uniqueVisitors": 3421,
  "totalBandwidth": 8934572819,
  "avgResponseTime": 124.5,
  "successRate": 98.7,
  "errorRate": 1.3,
  "requestsLast24h": 12456,
  "requestsLastHour": 523
}

Timeline Data

GET /api/v1/stats/timeline

Returns time-series data for requests, visitors, bandwidth, and response times.

Query Parameters:

  • service (optional, string) - Service name to filter by
  • service_type (optional, enum) - Type of service identifier (default: auto)
  • services[] (optional, string[]) - Array of service names for multi-service filtering
  • service_types[] (optional, enum[]) - Corresponding array of service types
  • host (optional, string) - Legacy parameter - Filter by backend/service name
  • hours (optional, integer 1-8760, default 168) - Number of hours to look back
  • exclude_own_ip (optional, boolean) - Exclude requests from your IP
  • exclude_services[] (optional, string[]) - Services to exclude your IP from
  • exclude_service_types[] (optional, enum[]) - Service types for exclude_services[]

Request:

# Last 7 days (default)
curl http://localhost:8080/api/v1/stats/timeline

# Last 24 hours
curl "http://localhost:8080/api/v1/stats/timeline?hours=24"

# Filter by service
curl "http://localhost:8080/api/v1/stats/timeline?service=api-service&service_type=backend_name&hours=48"

# Multi-service with exclude own IP
curl "http://localhost:8080/api/v1/stats/timeline?services[]=api&service_types[]=backend_name&services[]=web&service_types[]=host&exclude_own_ip=true&hours=24"

Response:

[
  {
    "timestamp": "2025-11-04T09:00:00Z",
    "requests": 345,
    "uniqueVisitors": 89,
    "bandwidth": 45678912,
    "avgResponseTime": 120.3
  },
  {
    "timestamp": "2025-11-04T10:00:00Z",
    "requests": 412,
    "uniqueVisitors": 102,
    "bandwidth": 52341567,
    "avgResponseTime": 115.7
  }
]

GET /api/v1/stats/timeline/status-codes

Returns status code distribution over time for stacked area charts.

Query Parameters:

  • service (optional, string) - Service name to filter by
  • service_type (optional, enum) - Type of service identifier (default: auto)
  • services[] (optional, string[]) - Array of service names for multi-service filtering
  • service_types[] (optional, enum[]) - Corresponding array of service types
  • host (optional, string) - Legacy parameter - Filter by backend/service name
  • hours (optional, integer 1-8760, default 168) - Number of hours to look back
  • exclude_own_ip (optional, boolean) - Exclude requests from your IP
  • exclude_services[] (optional, string[]) - Services to exclude your IP from
  • exclude_service_types[] (optional, enum[]) - Service types for exclude_services[]

Request:

curl "http://localhost:8080/api/v1/stats/timeline/status-codes?hours=24"

# With service filter
curl "http://localhost:8080/api/v1/stats/timeline/status-codes?service=api-service&service_type=backend_name&hours=48"

Response:

[
  {
    "timestamp": "2025-11-04T09:00:00Z",
    "status2xx": 320,
    "status3xx": 15,
    "status4xx": 8,
    "status5xx": 2
  }
]

GET /api/v1/stats/heatmap/traffic

Returns hourly traffic data grouped by day of week for heatmap visualization.

Query Parameters:

  • service (optional, string) - Service name to filter by
  • service_type (optional, enum) - Type of service identifier (default: auto)
  • services[] (optional, string[]) - Array of service names for multi-service filtering
  • service_types[] (optional, enum[]) - Corresponding array of service types
  • host (optional, string) - Legacy parameter - Filter by backend/service name
  • days (optional, integer 1-365, default 30) - Number of days to analyze
  • exclude_own_ip (optional, boolean) - Exclude requests from your IP
  • exclude_services[] (optional, string[]) - Services to exclude your IP from
  • exclude_service_types[] (optional, enum[]) - Service types for exclude_services[]

Request:

curl "http://localhost:8080/api/v1/stats/heatmap/traffic?days=30"

# With service filter
curl "http://localhost:8080/api/v1/stats/heatmap/traffic?service=web-app&service_type=host&days=14"

Response:

[
  {
    "dayOfWeek": "Monday",
    "hour": 0,
    "requests": 234
  },
  {
    "dayOfWeek": "Monday",
    "hour": 1,
    "requests": 156
  }
]

Top Statistics

GET /api/v1/stats/top/paths

Returns the most accessed paths/URLs with hits, visitors, response time, and bandwidth.

Query Parameters:

  • service (optional, string) - Service name to filter by
  • service_type (optional, enum) - Type of service identifier (default: auto)
  • services[] (optional, string[]) - Array of service names for multi-service filtering
  • service_types[] (optional, enum[]) - Corresponding array of service types
  • host (optional, string) - Legacy parameter - Filter by backend/service name
  • limit (optional, integer 1-100, default 10) - Number of results
  • exclude_own_ip (optional, boolean) - Exclude requests from your IP
  • exclude_services[] (optional, string[]) - Services to exclude your IP from
  • exclude_service_types[] (optional, enum[]) - Service types for exclude_services[]

Request:

curl "http://localhost:8080/api/v1/stats/top/paths?limit=20"

# With service filter and exclude own IP
curl "http://localhost:8080/api/v1/stats/top/paths?service=api-service&service_type=backend_name&exclude_own_ip=true&limit=20"

Response:

[
  {
    "path": "/api/v1/users",
    "hits": 12456,
    "uniqueVisitors": 3421,
    "avgResponseTime": 85.3,
    "totalBandwidth": 156789234
  },
  {
    "path": "/api/v1/products",
    "hits": 9823,
    "uniqueVisitors": 2134,
    "avgResponseTime": 120.7,
    "totalBandwidth": 98234567
  }
]

GET /api/v1/stats/top/countries

Returns countries with the most traffic.

Query Parameters:

  • host (optional, string) - Filter by backend/service name
  • limit (optional, integer 0-500, default 10) - Number of results (0 = unlimited)

Request:

curl "http://localhost:8080/api/v1/stats/top/countries?limit=50"

Response:

[
  {
    "country": "United States",
    "countryCode": "US",
    "requests": 45632,
    "uniqueVisitors": 12345,
    "bandwidth": 5678912345
  },
  {
    "country": "Germany",
    "countryCode": "DE",
    "requests": 23451,
    "uniqueVisitors": 5678,
    "bandwidth": 2345678901
  }
]

GET /api/v1/stats/top/ips

Returns IP addresses with the most requests.

Query Parameters:

  • host (optional, string) - Filter by backend/service name
  • limit (optional, integer 1-100, default 10) - Number of results

Request:

curl "http://localhost:8080/api/v1/stats/top/ips?limit=25"

Response:

[
  {
    "ip": "192.168.1.100",
    "requests": 5432,
    "bandwidth": 678912345,
    "country": "United States",
    "city": "New York",
    "asn": 15169,
    "asnOrg": "Google LLC"
  }
]

GET /api/v1/stats/top/user-agents

Returns the most common user agent strings.

Query Parameters:

  • host (optional, string) - Filter by backend/service name
  • limit (optional, integer 1-100, default 10) - Number of results

Request:

curl http://localhost:8080/api/v1/stats/top/user-agents

Response:

[
  {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...",
    "requests": 8765,
    "percentage": 12.5
  }
]

GET /api/v1/stats/top/browsers

Returns the most common browsers.

Query Parameters:

  • host (optional, string) - Filter by backend/service name
  • limit (optional, integer 1-100, default 10) - Number of results

Request:

curl http://localhost:8080/api/v1/stats/top/browsers

Response:

[
  {
    "browser": "Chrome",
    "version": "120.0",
    "requests": 45632,
    "percentage": 45.2
  },
  {
    "browser": "Firefox",
    "version": "121.0",
    "requests": 23451,
    "percentage": 23.2
  }
]

GET /api/v1/stats/top/operating-systems

Returns the most common operating systems.

Query Parameters:

  • host (optional, string) - Filter by backend/service name
  • limit (optional, integer 1-100, default 10) - Number of results

Request:

curl http://localhost:8080/api/v1/stats/top/operating-systems

Response:

[
  {
    "os": "Windows",
    "version": "10",
    "requests": 34567,
    "percentage": 52.3
  }
]

GET /api/v1/stats/top/asns

Returns Autonomous System Numbers with the most traffic.

Query Parameters:

  • host (optional, string) - Filter by backend/service name
  • limit (optional, integer 1-100, default 10) - Number of results

Request:

curl http://localhost:8080/api/v1/stats/top/asns

Response:

[
  {
    "asn": 15169,
    "organization": "Google LLC",
    "requests": 12456,
    "bandwidth": 1567894523
  }
]

GET /api/v1/stats/top/backends

Returns backend services with traffic and performance metrics.

Query Parameters:

  • host (optional, string) - Filter by backend/service name
  • limit (optional, integer 1-100, default 10) - Number of results

Request:

curl http://localhost:8080/api/v1/stats/top/backends

Response:

[
  {
    "backendName": "api-service@docker",
    "backendURL": "http://api:8080",
    "requests": 45632,
    "avgResponseTime": 125.7,
    "errorRate": 0.5,
    "bandwidth": 5678912345
  }
]

GET /api/v1/stats/top/referrers

Returns the top referrer URLs.

Query Parameters:

  • host (optional, string) - Filter by backend/service name
  • limit (optional, integer 1-100, default 10) - Number of results

Request:

curl http://localhost:8080/api/v1/stats/top/referrers

Response:

[
  {
    "referrer": "https://google.com/search?q=example",
    "requests": 2345,
    "uniqueVisitors": 1234
  }
]

GET /api/v1/stats/top/referrer-domains

Returns aggregated referrer traffic by domain.

Query Parameters:

  • host (optional, string) - Filter by backend/service name
  • limit (optional, integer, default 10) - Number of results (0 = unlimited)

Request:

curl "http://localhost:8080/api/v1/stats/top/referrer-domains?limit=20"

Response:

[
  {
    "domain": "google.com",
    "requests": 12345,
    "uniqueVisitors": 5678
  }
]

Distribution Statistics

GET /api/v1/stats/distribution/status-codes

Returns distribution of HTTP status codes.

Query Parameters:

  • host (optional, string) - Filter by backend/service name

Request:

curl http://localhost:8080/api/v1/stats/distribution/status-codes

Response:

[
  {
    "statusCode": 200,
    "count": 98765,
    "percentage": 89.2
  },
  {
    "statusCode": 404,
    "count": 5432,
    "percentage": 4.9
  }
]

GET /api/v1/stats/distribution/methods

Returns distribution of HTTP methods (GET, POST, etc.).

Query Parameters:

  • host (optional, string) - Filter by backend/service name

Request:

curl http://localhost:8080/api/v1/stats/distribution/methods

Response:

[
  {
    "method": "GET",
    "count": 85432,
    "percentage": 75.3
  },
  {
    "method": "POST",
    "count": 12345,
    "percentage": 10.9
  }
]

GET /api/v1/stats/distribution/protocols

Returns distribution of HTTP protocols (HTTP/1.1, HTTP/2, etc.).

Query Parameters:

  • host (optional, string) - Filter by backend/service name

Request:

curl http://localhost:8080/api/v1/stats/distribution/protocols

Response:

[
  {
    "protocol": "HTTP/2.0",
    "count": 67890,
    "percentage": 62.3
  },
  {
    "protocol": "HTTP/1.1",
    "count": 34567,
    "percentage": 31.7
  }
]

GET /api/v1/stats/distribution/tls-versions

Returns distribution of TLS/SSL versions.

Query Parameters:

  • host (optional, string) - Filter by backend/service name

Request:

curl http://localhost:8080/api/v1/stats/distribution/tls-versions

Response:

[
  {
    "tlsVersion": "TLS 1.3",
    "count": 78901,
    "percentage": 85.2
  },
  {
    "tlsVersion": "TLS 1.2",
    "count": 12345,
    "percentage": 13.3
  }
]

GET /api/v1/stats/distribution/device-types

Returns distribution of device types (desktop, mobile, tablet, bot).

Query Parameters:

  • host (optional, string) - Filter by backend/service name

Request:

curl http://localhost:8080/api/v1/stats/distribution/device-types

Response:

[
  {
    "deviceType": "desktop",
    "count": 67890,
    "percentage": 58.3
  },
  {
    "deviceType": "mobile",
    "count": 34567,
    "percentage": 29.6
  },
  {
    "deviceType": "bot",
    "count": 8765,
    "percentage": 7.5
  }
]

Performance Metrics

GET /api/v1/stats/performance/response-time

Returns response time metrics including min, max, avg, and percentiles.

Query Parameters:

  • host (optional, string) - Filter by backend/service name

Request:

curl http://localhost:8080/api/v1/stats/performance/response-time

Response:

{
  "min": 5.2,
  "max": 2345.8,
  "avg": 124.5,
  "p50": 95.3,
  "p95": 345.7,
  "p99": 567.2
}

Period Comparison

POST /api/v1/stats/compare

Compare traffic and analytics across 2 to 4 arbitrary time ranges in a single request. Each period returns its own full analytics snapshot (summary, timeline, top lists, distributions). Useful for "this week vs last week", "Q3 vs Q4", or any custom date range comparison.

Supports service filtering and hide-my-traffic query parameters (same as other stats endpoints).

Request body:

{
  "periods": [
    {
      "label": "Last 7 days",
      "start": "2025-11-01T00:00:00Z",
      "end":   "2025-11-08T00:00:00Z"
    },
    {
      "label": "Previous 7 days",
      "start": "2025-10-25T00:00:00Z",
      "end":   "2025-11-01T00:00:00Z"
    }
  ],
  "top_limit": 10
}
Field Type Required Description
periods array Yes Between 2 and 4 period objects
periods[].label string No Human-readable label (auto-generated if omitted)
periods[].start datetime Yes Period start (inclusive)
periods[].end datetime Yes Period end (exclusive, must be after start)
top_limit integer No Number of top items per list (default 10)

Request:

curl -X POST "http://localhost:8080/api/v1/stats/compare" \
  -H "Content-Type: application/json" \
  -d '{
    "periods": [
      {"label": "This week", "start": "2025-11-01T00:00:00Z", "end": "2025-11-08T00:00:00Z"},
      {"label": "Last week", "start": "2025-10-25T00:00:00Z", "end": "2025-11-01T00:00:00Z"}
    ],
    "top_limit": 10
  }'

Response:

{
  "generated_at": "2025-11-08T10:00:00Z",
  "top_limit": 10,
  "periods": [
    {
      "label": "This week",
      "start": "2025-11-01T00:00:00Z",
      "end":   "2025-11-08T00:00:00Z",
      "summary": { "total_requests": 87430, "unique_visitors": 2341, "..." : "..." },
      "timeline": [ { "hour": "2025-11-01T00:00:00Z", "requests": 312, "..." : "..." } ],
      "top_paths": [ { "path": "/api/v1/users", "hits": 5432, "..." : "..." } ],
      "status_code_distribution": [ { "status_code": 200, "count": 81000 } ],
      "device_types": [ { "device_type": "desktop", "count": 60000 } ]
    },
    {
      "label": "Last week",
      "...": "..."
    }
  ]
}

Comparison Snapshots

Snapshots let you save a comparison result and share it via a unique URL token. Snapshots are scoped to a session cookie (loglynx_compare_owner) so each browser session manages its own snapshots.

POST /api/v1/compare/snapshots

Store a comparison result for later retrieval.

Request body:

{
  "title": "Q3 vs Q4 2025",
  "payload": { "...": "ComparisonResult JSON object..." },
  "expires_at": "2026-01-01T00:00:00Z"
}

Request:

curl -X POST "http://localhost:8080/api/v1/compare/snapshots" \
  -H "Content-Type: application/json" \
  -d '{"title": "My comparison", "payload": { "..." : "..." }}'

Response:

{
  "id": 1,
  "token": "a1b2c3d4e5f6789abc",
  "title": "My comparison",
  "payload": "{...}",
  "active": true,
  "expires_at": null,
  "created_at": "2025-11-08T10:00:00Z",
  "updated_at": "2025-11-08T10:00:00Z"
}

GET /api/v1/compare/snapshots

List all snapshots owned by the current session.

curl "http://localhost:8080/api/v1/compare/snapshots"

GET /api/v1/compare/snapshots/{token}

Retrieve a snapshot by token. The snapshot page is accessible at /compare/{token}.

curl "http://localhost:8080/api/v1/compare/snapshots/a1b2c3d4e5f6789abc"

PATCH /api/v1/compare/snapshots/{token}

Update a snapshot's active state or expiry date.

curl -X PATCH "http://localhost:8080/api/v1/compare/snapshots/a1b2c3d4e5f6789abc" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'

DELETE /api/v1/compare/snapshots/{token}

Delete a snapshot permanently.

curl -X DELETE "http://localhost:8080/api/v1/compare/snapshots/a1b2c3d4e5f6789abc"

Recent Requests

GET /api/v1/requests/recent

Returns the most recent HTTP requests with full details.

Query Parameters:

  • service (optional, string) - Service name to filter by
  • service_type (optional, enum) - Type of service identifier (default: auto)
  • services[] (optional, string[]) - Array of service names for multi-service filtering
  • service_types[] (optional, enum[]) - Corresponding array of service types
  • host (optional, string) - Legacy parameter - Filter by backend/service name
  • limit (optional, integer 1-1000, default 100) - Number of results
  • offset (optional, integer >= 0, default 0) - Pagination offset
  • exclude_own_ip (optional, boolean) - Exclude requests from your IP
  • exclude_services[] (optional, string[]) - Services to exclude your IP from
  • exclude_service_types[] (optional, enum[]) - Service types for exclude_services[]

Request:

# Last 100 requests (default)
curl http://localhost:8080/api/v1/requests/recent

# Last 50 requests
curl "http://localhost:8080/api/v1/requests/recent?limit=50"

# Pagination (skip first 100)
curl "http://localhost:8080/api/v1/requests/recent?limit=100&offset=100"

# Filter by service and exclude own IP
curl "http://localhost:8080/api/v1/requests/recent?service=api-service&exclude_own_ip=true&limit=50"

# Hide my traffic only on admin panel
curl "http://localhost:8080/api/v1/requests/recent?exclude_own_ip=true&exclude_services[]=admin-panel&exclude_service_types[]=backend_name"

Response:

[
  {
    "id": 125487,
    "timestamp": "2025-11-04T10:30:15Z",
    "clientIP": "192.168.1.100",
    "method": "GET",
    "protocol": "HTTP/2.0",
    "host": "api.example.com",
    "path": "/api/v1/users/123",
    "statusCode": 200,
    "responseSize": 4567,
    "responseTimeMs": 85.3,
    "userAgent": "Mozilla/5.0...",
    "browser": "Chrome",
    "browserVersion": "120.0",
    "os": "Windows",
    "osVersion": "10",
    "deviceType": "desktop",
    "backendName": "api-service@docker",
    "geoCountry": "US",
    "geoCity": "New York",
    "asn": 15169,
    "asnOrg": "Google LLC"
  }
]

Real-time Streaming

GET /api/v1/realtime/metrics

Returns a single snapshot of current real-time metrics.

Query Parameters:

  • host (optional, string) - Filter by backend/service name

Request:

curl http://localhost:8080/api/v1/realtime/metrics

Response:

{
  "request_rate": 45.3,
  "error_rate": 2.3,
  "bandwidth_rate": 1048576.5,
  "avg_response_time": 89.5,
  "active_connections": 123,
  "status_2xx": 150,
  "status_4xx": 5,
  "status_5xx": 1,
  "timestamp": "2025-11-03T14:32:15Z",
  "top_ips": [
    {
      "ip": "192.168.1.100",
      "country": "US",
      "request_rate": 12.5,
      "bandwidth": 5242880,
      "bandwidth_rate": 349525.3
    }
  ],
  "latest_requests": [
    {
      "id": 12345,
      "timestamp": "2025-11-03T14:32:15Z",
      "method": "GET",
      "host": "api.example.com",
      "backend_name": "api-service",
      "path": "/api/v1/users",
      "status_code": 200,
      "response_time_ms": 45.2,
      "geo_country": "US",
      "client_ip": "192.168.1.100"
    }
  ]
}

Response (Up to v1.0.1):

{
  "timestamp": "2025-11-04T10:30:00Z",
  "requestsPerSecond": 45.3,
  "activeConnections": 123,
  "errorRate": 0.8,
  "avgResponseTime": 120.5,
  "status2xx": 1234,
  "status4xx": 12,
  "status5xx": 3,
  "topPaths": [
    {
      "path": "/api/v1/users",
      "requests": 234
    }
  ]
}

GET /api/v1/realtime/stream

Server-Sent Events (SSE) endpoint that streams real-time metrics. Updates every 1 second (v1.0.2+) or 2 seconds (v1.0.1).

Query Parameters:

  • host (optional, string) - Filter by backend/service name

Request:

# Using curl
curl -N http://localhost:8080/api/v1/realtime/stream

# Using JavaScript EventSource
const eventSource = new EventSource('http://localhost:8080/api/v1/realtime/stream');
eventSource.onmessage = (event) => {
  const metrics = JSON.parse(event.data);
  console.log('Real-time metrics:', metrics);
};

Response (SSE stream) (v1.0.2+):

data: {"request_rate":45.3,"error_rate":2.3,"avg_response_time":89.5,"active_connections":123,"status_2xx":150,"status_4xx":5,"status_5xx":1,"timestamp":"2025-11-03T14:32:15Z",...}

Response (SSE stream) (Up to v1.0.1):

data: {"timestamp":"2025-11-04T10:30:00Z","requestsPerSecond":45.3,"activeConnections":123,...}

data: {"timestamp":"2025-11-04T10:30:02Z","requestsPerSecond":48.1,"activeConnections":125,...}

data: {"timestamp":"2025-11-04T10:30:04Z","requestsPerSecond":42.7,"activeConnections":120,...}

GET /api/v1/realtime/services

Returns real-time metrics broken down by service/backend.

Request:

curl http://localhost:8080/api/v1/realtime/services

Response (v1.0.2+):

[
  {
    "service_name": "api-service@docker",
    "request_rate": 25.3
  },
  {
    "service_name": "web-service@docker",
    "request_rate": 20.0
  }
]

Response (Up to v1.0.1):

[
  {
    "serviceName": "api-service@docker",
    "requestsPerSecond": 25.3,
    "errorRate": 0.5,
    "avgResponseTime": 95.2
  },
  {
    "serviceName": "web-service@docker",
    "requestsPerSecond": 20.0,
    "errorRate": 1.2,
    "avgResponseTime": 145.8
  }
]

IP Analytics

GET /api/v1/ip/search

Search for IP addresses by partial match with basic statistics.

Query Parameters:

  • q (required, string) - IP address search query (partial match supported)
  • limit (optional, integer 1-100, default 20) - Number of results

Request:

# Search for IPs starting with 192.168
curl "http://localhost:8080/api/v1/ip/search?q=192.168"

# Search with limit
curl "http://localhost:8080/api/v1/ip/search?q=10.0&limit=50"

Response:

[
  {
    "ip": "192.168.1.100",
    "requests": 5432,
    "lastSeen": "2025-11-04T10:25:00Z",
    "country": "United States",
    "city": "New York"
  }
]

GET /api/v1/ip/{ip}/stats

Returns comprehensive statistics for a specific IP including request counts, bandwidth, geographic data, and ASN information.

Request:

curl http://localhost:8080/api/v1/ip/192.168.1.100/stats

Response:

{
  "ip": "192.168.1.100",
  "totalRequests": 5432,
  "uniquePaths": 234,
  "totalBandwidth": 678912345,
  "avgResponseTime": 105.3,
  "firstSeen": "2025-10-15T08:30:00Z",
  "lastSeen": "2025-11-04T10:25:00Z",
  "country": "United States",
  "city": "New York",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "asn": 15169,
  "asnOrg": "Google LLC",
  "mostCommonBrowser": "Chrome 120.0",
  "mostCommonOS": "Windows 10",
  "mostCommonDeviceType": "desktop"
}

GET /api/v1/ip/{ip}/timeline

Returns time-series data for requests from the specified IP address.

Query Parameters:

  • hours (optional, integer 1-8760, default 168) - Number of hours to look back

Request:

curl "http://localhost:8080/api/v1/ip/192.168.1.100/timeline?hours=24"

Response:

[
  {
    "timestamp": "2025-11-04T09:00:00Z",
    "requests": 45,
    "bandwidth": 567891,
    "avgResponseTime": 98.3
  }
]

GET /api/v1/ip/{ip}/heatmap

Returns hourly traffic data grouped by day of week for the specified IP address.

Query Parameters:

  • days (optional, integer 1-365, default 30) - Number of days to analyze

Request:

curl "http://localhost:8080/api/v1/ip/192.168.1.100/heatmap?days=30"

Response:

[
  {
    "dayOfWeek": "Monday",
    "hour": 10,
    "requests": 34
  }
]

GET /api/v1/ip/{ip}/top/paths

Returns the most accessed paths by the specified IP address.

Query Parameters:

  • limit (optional, integer 1-100, default 20) - Number of results

Request:

curl "http://localhost:8080/api/v1/ip/192.168.1.100/top/paths?limit=10"

Response:

[
  {
    "path": "/api/v1/users",
    "hits": 234,
    "avgResponseTime": 85.3
  }
]

GET /api/v1/ip/{ip}/top/backends

Returns backend services most accessed by the specified IP address.

Query Parameters:

  • limit (optional, integer 1-100, default 10) - Number of results

Request:

curl http://localhost:8080/api/v1/ip/192.168.1.100/top/backends

Response:

[
  {
    "backendName": "api-service@docker",
    "requests": 345,
    "avgResponseTime": 95.2
  }
]

GET /api/v1/ip/{ip}/distribution/status-codes

Returns distribution of HTTP status codes for requests from the specified IP address.

Request:

curl http://localhost:8080/api/v1/ip/192.168.1.100/distribution/status-codes

Response:

[
  {
    "statusCode": 200,
    "count": 4567,
    "percentage": 92.3
  }
]

GET /api/v1/ip/{ip}/distribution/device-types

Returns distribution of device types for the specified IP address.

Request:

curl http://localhost:8080/api/v1/ip/192.168.1.100/distribution/device-types

Response:

[
  {
    "deviceType": "desktop",
    "count": 4890,
    "percentage": 95.2
  }
]

GET /api/v1/ip/{ip}/top/browsers

Returns the most common browsers used by the specified IP address.

Query Parameters:

  • limit (optional, integer 1-100, default 10) - Number of results

Request:

curl http://localhost:8080/api/v1/ip/192.168.1.100/top/browsers

Response:

[
  {
    "browser": "Chrome",
    "version": "120.0",
    "requests": 4567,
    "percentage": 89.2
  }
]

GET /api/v1/ip/{ip}/top/operating-systems

Returns the most common operating systems used by the specified IP address.

Query Parameters:

  • limit (optional, integer 1-100, default 10) - Number of results

Request:

curl http://localhost:8080/api/v1/ip/192.168.1.100/top/operating-systems

Response:

[
  {
    "os": "Windows",
    "version": "10",
    "requests": 4890,
    "percentage": 95.3
  }
]

GET /api/v1/ip/{ip}/performance/response-time

Returns response time metrics for requests from the specified IP address.

Request:

curl http://localhost:8080/api/v1/ip/192.168.1.100/performance/response-time

Response:

{
  "min": 12.3,
  "max": 456.7,
  "avg": 105.3,
  "p50": 95.2,
  "p95": 234.5,
  "p99": 345.8
}

GET /api/v1/ip/{ip}/recent-requests

Returns the most recent HTTP requests from the specified IP address with full details.

Query Parameters:

  • limit (optional, integer 1-500, default 50) - Number of results

Request:

curl "http://localhost:8080/api/v1/ip/192.168.1.100/recent-requests?limit=25"

Response:

[
  {
    "id": 125487,
    "timestamp": "2025-11-04T10:30:15Z",
    "method": "GET",
    "path": "/api/v1/users/123",
    "statusCode": 200,
    "responseTimeMs": 85.3,
    "browser": "Chrome 120.0",
    "os": "Windows 10"
  }
]

IP Tagging

Assign friendly names and searchable tags to IP addresses for easier identification in the dashboard.

POST /api/v1/ip/tags

Create or update a tag record for an IP address.

Request body:

{
  "ip_address": "192.168.1.100",
  "friendly_name": "Office VPN",
  "tags": "internal,trusted"
}
curl -X POST "http://localhost:8080/api/v1/ip/tags" \
  -H "Content-Type: application/json" \
  -d '{"ip_address": "192.168.1.100", "friendly_name": "Office VPN", "tags": "internal,trusted"}'

Response:

{
  "id": 1,
  "ip_address": "192.168.1.100",
  "friendly_name": "Office VPN",
  "tags": "internal,trusted",
  "created_at": "2025-11-04T10:00:00Z",
  "updated_at": "2025-11-04T10:00:00Z"
}

GET /api/v1/ip/tags

Returns all IP tag records.

curl "http://localhost:8080/api/v1/ip/tags"

GET /api/v1/ip/tags/{ip}

Returns the tag record for a specific IP address.

curl "http://localhost:8080/api/v1/ip/tags/192.168.1.100"

Response:

{
  "id": 1,
  "ip_address": "192.168.1.100",
  "friendly_name": "Office VPN",
  "tags": "internal,trusted",
  "created_at": "2025-11-04T10:00:00Z",
  "updated_at": "2025-11-04T10:30:00Z"
}

DELETE /api/v1/ip/tags/{ip}

Removes all tag data assigned to the specified IP address.

curl -X DELETE "http://localhost:8080/api/v1/ip/tags/192.168.1.100"

Utility Endpoints

GET /api/v1/services

Returns a list of all available services with their identification types and request counts.

Request:

curl http://localhost:8080/api/v1/services

Response:

[
  {
    "name": "api-service-prod",
    "type": "backend_name",
    "count": 45632
  },
  {
    "name": "http://api:8080",
    "type": "backend_url",
    "count": 23451
  },
  {
    "name": "web.example.com",
    "type": "host",
    "count": 12345
  }
]

Service Types (priority-based):

  1. backend_name - Traefik backend name (highest priority)
  2. backend_url - Backend URL
  3. host - HTTP Host header (lowest priority)

Use this endpoint to discover available services for filtering in other API calls.

GET /api/v1/domains (DEPRECATED)

Deprecated: Use /api/v1/services endpoint instead for better service identification.

Returns a list of available backend names for filtering (only returns backend_name field values).

Request:

curl http://localhost:8080/api/v1/domains

Response:

[
  {
    "domain": "api-service-prod",
    "request_count": 45632
  },
  {
    "domain": "web-service",
    "request_count": 23451
  }
]

GET /api/v1/stats/log-processing

Returns information about log file processing progress. The percentage is intelligently calculated based on:

  1. Record-based estimation: Calculates average bytes per record and estimates total records in file
  2. Byte-based fallback: Uses file position vs file size if records aren't available yet
  3. Real-time updates: Position updates every 500ms during active processing for smooth progress tracking

Request:

curl http://localhost:8080/api/v1/stats/log-processing

Response:

[
  {
    "log_source_name": "traefik-access",
    "file_size": 104857600,
    "bytes_processed": 52428800,
    "percentage": 50.0,
    "last_processed_at": "2025-11-06T10:30:15Z"
  }
]

Fields:

  • log_source_name: Name of the log source being processed
  • file_size: Total size of the log file in bytes
  • bytes_processed: Number of bytes read from the file so far
  • percentage: Processing progress (0-100%), calculated using intelligent estimation based on processed records
  • last_processed_at: Timestamp of the last processing update (updates every 500ms during active processing)

Common Query Parameters

Most endpoints support the following optional query parameters:

Service Filtering Parameters

Parameter Type Default Description
service string - Service name to filter by
service_type enum auto Type of service identifier: auto, backend_name, backend_url, host
services[] string[] - Array of service names for multi-service filtering
service_types[] enum[] - Corresponding array of service types
host string - Legacy parameter - Filter by backend/service name (equivalent to service with service_type=auto)

Hide My Traffic Parameters

Parameter Type Default Description
exclude_own_ip boolean false Exclude requests from your IP address
exclude_services[] string[] - Service names to exclude your IP from (if omitted, excludes from all)
exclude_service_types[] enum[] - Service types corresponding to exclude_services[]

Pagination & Limits

Parameter Type Default Description
limit integer varies Maximum number of results to return (range varies by endpoint)
offset integer 0 Pagination offset for result sets

Time Range Parameters

Parameter Type Default Description
hours integer 168 Number of hours to look back (1-8760, up to 1 year)
days integer 30 Number of days to analyze (1-365)

Response Formats

All API responses return JSON with appropriate HTTP status codes.

Success Response (200 OK)

{
  "field1": "value1",
  "field2": 123
}

Empty Results (200 OK)

[]

Error Response (400 Bad Request)

{
  "error": "Invalid parameter: hours must be between 1 and 8760"
}

Server Error (500 Internal Server Error)

{
  "error": "Internal server error"
}

Error Handling

HTTP Status Codes

  • 200 OK - Successful request
  • 400 Bad Request - Invalid parameters or malformed request
  • 404 Not Found - Endpoint or resource not found
  • 500 Internal Server Error - Server-side error

Common Error Scenarios

Missing Required Parameter:

curl "http://localhost:8080/api/v1/ip/search"
# Response: 400 Bad Request
# {"error": "Missing required parameter: q"}

Invalid Parameter Value:

curl "http://localhost:8080/api/v1/stats/timeline?hours=10000"
# Response: 400 Bad Request
# {"error": "Invalid parameter: hours must be between 1 and 8760"}

Invalid IP Address:

curl "http://localhost:8080/api/v1/ip//stats"
# Response: 400 Bad Request
# {"error": "IP address is required"}

Rate Limiting

Currently, LogLynx does not implement rate limiting. For production deployments, consider adding rate limiting at the reverse proxy level (e.g., Traefik, Nginx).

CORS Configuration

All API endpoints support Cross-Origin Resource Sharing (CORS):

  • Allowed Origins: * (all origins)
  • Allowed Methods: GET, POST, PUT, DELETE, OPTIONS
  • Allowed Headers: Content-Type, Authorization, X-Requested-With, etc.

OpenAPI Specification

A complete OpenAPI 3.0 specification is available in the repository:

File: openapi.yaml

Usage:

# View in Swagger Editor
# Visit: https://editor.swagger.io/
# Import: openapi.yaml

# Generate API client (Python example)
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g python \
  -o ./python-client

# Generate API client (JavaScript/TypeScript example)
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./ts-client

Example Use Cases

Monitoring Dashboard Integration

// Fetch real-time metrics every 5 seconds
setInterval(async () => {
  const response = await fetch('http://localhost:8080/api/v1/realtime/metrics');
  const metrics = await response.json();
  updateDashboard(metrics);
}, 5000);

Custom Analytics Report

# Generate a report for specific service in last 7 days
curl "http://localhost:8080/api/v1/stats/summary?service=api-service&service_type=backend_name" > summary.json
curl "http://localhost:8080/api/v1/stats/timeline?service=api-service&service_type=backend_name&hours=168" > timeline.json
curl "http://localhost:8080/api/v1/stats/top/paths?service=api-service&service_type=backend_name&limit=50" > top-paths.json

# Generate report excluding your own traffic
curl "http://localhost:8080/api/v1/stats/summary?service=api-service&service_type=backend_name&exclude_own_ip=true" > summary-clean.json

IP Investigation

# Investigate suspicious IP activity
curl "http://localhost:8080/api/v1/ip/192.168.1.100/stats" > ip-stats.json
curl "http://localhost:8080/api/v1/ip/192.168.1.100/recent-requests?limit=100" > ip-requests.json
curl "http://localhost:8080/api/v1/ip/192.168.1.100/distribution/status-codes" > ip-status-codes.json

Real-time Event Stream Processing

import requests
import json

url = 'http://localhost:8080/api/v1/realtime/stream'
response = requests.get(url, stream=True)

for line in response.iter_lines():
    if line and line.startswith(b'data: '):
        data = json.loads(line[6:])  # Remove 'data: ' prefix
        print(f"Requests/sec: {data['requestsPerSecond']}")
        print(f"Error rate: {data['errorRate']}%")

API Versioning

Current API version: v1

All endpoints are prefixed with /api/v1. Future versions will use /api/v2, etc., allowing backward compatibility.

Support

For API-related issues, feature requests, or questions:

Migration Guide

Upgrading from Legacy host Parameter

The legacy host parameter is still supported for backward compatibility, but it's recommended to migrate to the new service filtering parameters for better control and multi-service support.

Old way (still works):

curl "http://localhost:8080/api/v1/stats/summary?host=api-service"

New way (recommended):

# Single service with auto-detection
curl "http://localhost:8080/api/v1/stats/summary?service=api-service&service_type=auto"

# Single service with specific type
curl "http://localhost:8080/api/v1/stats/summary?service=api-service&service_type=backend_name"

# Multiple services
curl "http://localhost:8080/api/v1/stats/summary?services[]=api-prod&service_types[]=backend_name&services[]=api-staging&service_types[]=backend_name"

New Features Available

  1. Service Type Control: Specify exactly which service identifier to use
  2. Multi-Service Filtering: Analyze multiple services in a single request
  3. Hide My Traffic: Exclude your own IP from analytics
  4. Service Discovery: Use /services endpoint to discover available services with types

Last Updated: June 2026

LogLynx Wiki

Getting Started

Deployment

Reverse proxy recommended configuration

Key features

Side features

Quick Links

API Endpoints

Configuration

Deployment

Support

Clone this wiki locally