openapi.yaml

openapi: 3.0.3
info:
  title: LogLynx API
  description: |
    LogLynx is an advanced log analytics platform for analyzing Traefik access logs and other log sources.
    This API provides comprehensive statistics, real-time metrics, and detailed insights into your web traffic.

    ## Features
    - **Summary Statistics**: Get overall metrics including requests, visitors, bandwidth, and response times
    - **Timeline Data**: Analyze traffic patterns over time with customizable time ranges
    - **Top Statistics**: Identify top paths, countries, IPs, user agents, and more
    - **Distribution Analytics**: View distributions of status codes, HTTP methods, protocols, and device types
    - **Real-time Monitoring**: Stream live metrics via Server-Sent Events (SSE)
    - **Performance Metrics**: Track response times and backend health
    - **Geographic Analytics**: Analyze traffic by country and region
    - **IP Analytics**: Deep-dive analytics for specific IP addresses
    - **Service Filtering**: Filter by backend name, URL, or host with intelligent auto-detection

    ## Service Filtering
    Most endpoints support service-based filtering with the following parameters:

    ### Single Service Filtering
    - `service`: Service name to filter by (e.g., "api-service", "web-frontend")
    - `service_type`: Type of service identifier
      - `auto` (default): Automatically detects and uses backend_name, backend_url, or host
      - `backend_name`: Filter by Traefik backend name
      - `backend_url`: Filter by backend URL
      - `host`: Filter by HTTP Host header
    - `host`: Legacy parameter (backward compatible), equivalent to `service` with `service_type=auto`

    ### Multi-Service Filtering (Array Parameters)
    For filtering across multiple services simultaneously, use array parameters:
    - `services[]`: Array of service names (can be repeated)
    - `service_types[]`: Corresponding array of service types (must match length of services[])

    **Example**: Filter for two services
    ```
    /api/v1/stats/summary?services[]=api-service&service_types[]=backend_name&services[]=web-app&service_types[]=host
    ```

    ## Hide My Traffic
    Endpoints that return request data support excluding your own IP address:
    - `exclude_own_ip`: Set to `true` to exclude requests from your IP (boolean)
    - `exclude_services[]`: Optional array of service names to exclude your IP from (if omitted, excludes from all services)
    - `exclude_service_types[]`: Corresponding array of service types for exclude_services[]

    **Example**: Hide my traffic only on specific services
    ```
    /api/v1/requests/recent?exclude_own_ip=true&exclude_services[]=admin-panel&exclude_service_types[]=backend_name
    ```

    ## Common Query Parameters
    - `limit`: Maximum number of results (varies by endpoint, typically 1-100)
    - `offset`: Pagination offset for results
    - `hours`: Time range in hours (1-8760, default varies by endpoint)
    - `days`: Time range in days (1-365, default varies by endpoint)

  version: 1.0.3
  contact:
    name: LogLynx Support
    url: https://github.com/k0lin/loglynx
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:8080/api/v1
    description: Local development server

tags:
  - name: Summary
    description: Overall statistics and summary data
  - name: Timeline
    description: Time-series data and trends
  - name: Top Statistics
    description: Top items by various metrics
  - name: Distributions
    description: Distribution of categorical data
  - name: Performance
    description: Response time and performance metrics
  - name: Real-time
    description: Live metrics and streaming data
  - name: Requests
    description: Individual request data
  - name: System
    description: System information and log processing stats
  - name: IP Analytics
    description: IP-specific statistics and analytics
  - name: Widget
    description: Compact widget endpoints for iframe embedding

paths:
  /stats/summary:
    get:
      tags:
        - Summary
      summary: Get summary statistics
      description: |
        Returns overall statistics including total requests, unique visitors, bandwidth, success rates, and top items.

        **Service Filtering**: Use `service` and `service_type` for single service filtering, or `services[]` and `service_types[]` for multi-service filtering.
        Legacy `host` parameter is supported for backward compatibility.

        **Hide My Traffic**: Use `exclude_own_ip=true` to exclude your IP from results.
      operationId: getSummary
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'
      responses:
        '200':
          description: Summary statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsSummary'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/timeline:
    get:
      tags:
        - Timeline
      summary: Get timeline statistics
      description: |
        Returns time-series data for requests, visitors, bandwidth, and response times.
        Supports service filtering and hide my traffic functionality.
      operationId: getTimeline
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'
      responses:
        '200':
          description: Timeline data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimelineData'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/timeline/status-codes:
    get:
      tags:
        - Timeline
      summary: Get status code timeline
      description: |
        Returns status code distribution over time for stacked area charts.
        Supports service filtering and hide my traffic functionality.
      operationId: getStatusCodeTimeline
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'
      responses:
        '200':
          description: Status code timeline data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StatusCodeTimelineData'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/heatmap/traffic:
    get:
      tags:
        - Timeline
      summary: Get traffic heatmap
      description: |
        Returns hourly traffic data grouped by day of week for heatmap visualization.
        Supports service filtering and hide my traffic functionality.
      operationId: getTrafficHeatmap
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/DaysParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'
      responses:
        '200':
          description: Traffic heatmap data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrafficHeatmapData'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/top/paths:
    get:
      tags:
        - Top Statistics
      summary: Get top paths
      description: Returns most accessed paths/URLs with hits, visitors, response time, and bandwidth
      operationId: getTopPaths
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'

      responses:
        '200':
          description: Top paths
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PathStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/top/countries:
    get:
      tags:
        - Top Statistics
      summary: Get top countries
      description: Returns countries with the most traffic
      operationId: getTopCountries
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'
        - name: limit
          in: query
          description: Maximum number of results (0-500, default 10)
          schema:
            type: integer
            minimum: 0
            maximum: 500
            default: 10
      responses:
        '200':
          description: Top countries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CountryStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/top/ips:
    get:
      tags:
        - Top Statistics
      summary: Get top IP addresses
      description: Returns IP addresses with the most requests
      operationId: getTopIPs
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'

      responses:
        '200':
          description: Top IP addresses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IPStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/top/user-agents:
    get:
      tags:
        - Top Statistics
      summary: Get top user agents
      description: Returns most common user agent strings
      operationId: getTopUserAgents
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'

      responses:
        '200':
          description: Top user agents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserAgentStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/top/browsers:
    get:
      tags:
        - Top Statistics
      summary: Get top browsers
      description: Returns most common browsers
      operationId: getTopBrowsers
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'

      responses:
        '200':
          description: Top browsers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BrowserStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/top/operating-systems:
    get:
      tags:
        - Top Statistics
      summary: Get top operating systems
      description: Returns most common operating systems
      operationId: getTopOperatingSystems
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'

      responses:
        '200':
          description: Top operating systems
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OSStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/top/asns:
    get:
      tags:
        - Top Statistics
      summary: Get top ASNs
      description: Returns Autonomous System Numbers with the most traffic
      operationId: getTopASNs
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'

      responses:
        '200':
          description: Top ASNs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ASNStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/top/backends:
    get:
      tags:
        - Top Statistics
      summary: Get top backends
      description: Returns backend services with traffic and performance metrics
      operationId: getTopBackends
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'

      responses:
        '200':
          description: Top backends
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BackendStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/top/referrers:
    get:
      tags:
        - Top Statistics
      summary: Get top referrers
      description: Returns top referrer URLs
      operationId: getTopReferrers
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'
        - name: limit
          in: query
          description: Maximum number of results (1-100, default 10)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        '200':
          description: Top referrers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReferrerStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/top/referrer-domains:
    get:
      tags:
        - Top Statistics
      summary: Get top referrer domains
      description: Returns aggregated referrer traffic by domain
      operationId: getTopReferrerDomains
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'
        - name: limit
          in: query
          description: Maximum number of results (0 = unlimited, default 10)
          schema:
            type: integer
            minimum: 0
            default: 10
      responses:
        '200':
          description: Top referrer domains
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReferrerDomainStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/distribution/status-codes:
    get:
      tags:
        - Distributions
      summary: Get status code distribution
      description: Returns distribution of HTTP status codes
      operationId: getStatusCodeDistribution
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'

      responses:
        '200':
          description: Status code distribution
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StatusCodeStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/distribution/methods:
    get:
      tags:
        - Distributions
      summary: Get HTTP method distribution
      description: Returns distribution of HTTP methods (GET, POST, etc.)
      operationId: getMethodDistribution
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'

      responses:
        '200':
          description: HTTP method distribution
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MethodStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/distribution/protocols:
    get:
      tags:
        - Distributions
      summary: Get protocol distribution
      description: Returns distribution of HTTP protocols (HTTP/1.1, HTTP/2, etc.)
      operationId: getProtocolDistribution
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'

      responses:
        '200':
          description: Protocol distribution
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProtocolStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/distribution/tls-versions:
    get:
      tags:
        - Distributions
      summary: Get TLS version distribution
      description: Returns distribution of TLS/SSL versions
      operationId: getTLSVersionDistribution
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'

      responses:
        '200':
          description: TLS version distribution
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TLSVersionStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/distribution/device-types:
    get:
      tags:
        - Distributions
      summary: Get device type distribution
      description: Returns distribution of device types (desktop, mobile, tablet, bot)
      operationId: getDeviceTypeDistribution
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'

      responses:
        '200':
          description: Device type distribution
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeviceTypeStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/performance/response-time:
    get:
      tags:
        - Performance
      summary: Get response time statistics
      description: Returns response time metrics including min, max, avg, and percentiles
      operationId: getResponseTimeStats
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/HoursParam'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'

      responses:
        '200':
          description: Response time statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseTimeStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /stats/log-processing:
    get:
      tags:
        - System
      summary: Get log processing statistics
      description: |
        Returns information about log file processing progress.
        
        **Percentage Calculation:**
        The processing percentage is intelligently calculated using:
        1. **Record-based estimation**: Calculates average bytes per record and estimates total records in file for accurate progress
        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
        
        **Use Cases:**
        - Monitor initial log import progress
        - Track ongoing log processing status
        - Display loading screens with accurate ETAs
        - Ensure logs are fully processed before showing analytics
      operationId: getLogProcessingStats
      responses:
        '200':
          description: Log processing statistics
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LogProcessingStats'
              example:
                - log_source_name: "traefik-access"
                  file_size: 104857600
                  bytes_processed: 52428800
                  percentage: 50.0
                  last_processed_at: "2025-11-06T10:30:15Z"
        '500':
          $ref: '#/components/responses/InternalServerError'

  /requests/recent:
    get:
      tags:
        - Requests
      summary: Get recent requests
      description: Returns the most recent HTTP requests with full details
      operationId: getRecentRequests
      parameters:
        - $ref: '#/components/parameters/ServiceFilter'
        - $ref: '#/components/parameters/ServiceTypeFilter'
        - $ref: '#/components/parameters/ServicesArray'
        - $ref: '#/components/parameters/ServiceTypesArray'
        - $ref: '#/components/parameters/HostFilter'
        - $ref: '#/components/parameters/ExcludeOwnIP'
        - $ref: '#/components/parameters/ExcludeServices'
        - $ref: '#/components/parameters/ExcludeServiceTypes'
        - name: limit
          in: query
          description: Maximum number of results (1-1000, default 100)
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - name: offset
          in: query
          description: Pagination offset
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Recent requests
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HTTPRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /realtime/metrics:
    get:
      tags:
        - Real-time
      summary: Get current real-time metrics
      description: Returns a single snapshot of current real-time metrics
      operationId: getCurrentMetrics
      responses:
        '200':
          description: Current real-time metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeMetrics'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /realtime/services:
    get:
      tags:
        - Real-time
      summary: Get per-service metrics
      description: Returns real-time metrics broken down by service/backend
      operationId: getPerServiceMetrics
      responses:
        '200':
          description: Per-service metrics
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceMetrics'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /realtime/stream:
    get:
      tags:
        - Real-time
      summary: Stream real-time metrics
      description: |
        Server-Sent Events (SSE) endpoint that streams real-time metrics.
        Connect using EventSource API in JavaScript or any SSE client.
        
        Example JavaScript:
        ```javascript
        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);
        };
        ```
      operationId: streamMetrics
      responses:
        '200':
          description: SSE stream of real-time metrics
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/RealtimeMetrics'

  /services:
    get:
      tags:
        - System
      summary: Get available services with types
      description: |
        Returns list of all available services with their identification types and request counts.

        **Service Types** (priority-based):
        1. `backend_name`: Traefik backend name (highest priority)
        2. `backend_url`: Backend URL
        3. `host`: HTTP Host header (lowest priority)

        The API intelligently selects the best available identifier for each service.
        Use this endpoint to discover available services for filtering in other API calls.
      operationId: getServices
      responses:
        '200':
          description: List of services with types and request counts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceInfo'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /widget/data:
    get:
      tags:
        - Widget
      summary: Get real-time widget data
      description: |
        Returns compact real-time metrics optimized for widget embedding.
        Shows data from the last hour with requests per minute calculation.
        
        **Note**: This endpoint is only available when `WIDGET_ENABLED=true` (default).
      operationId: getWidgetData
      responses:
        '200':
          description: Real-time widget data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetRealtimeData'
        '404':
          description: Widget endpoints disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /widget/summary:
    get:
      tags:
        - Widget
      summary: Get widget summary data for a time period
      description: |
        Returns compact summary statistics for embedding in widgets.
        Optimized for displaying aggregated data over a time period.
        
        **Note**: This endpoint is only available when `WIDGET_ENABLED=true` (default).
      operationId: getWidgetSummary
      parameters:
        - name: hours
          in: query
          description: Number of hours to analyze (1-720 for up to 30 days, default 24)
          schema:
            type: integer
            minimum: 1
            maximum: 720
            default: 24
            example: 24
      responses:
        '200':
          description: Widget summary data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetSummaryData'
        '404':
          description: Widget endpoints disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /widget/timeline:
    get:
      tags:
        - Widget
      summary: Get widget timeline data
      description: |
        Returns compact timeline data optimized for sparkline charts in widgets.
        Returns up to 30 data points for periods <= 24 hours, or 50 points for longer periods.
        
        **Note**: This endpoint is only available when `WIDGET_ENABLED=true` (default).
      operationId: getWidgetTimeline
      parameters:
        - name: hours
          in: query
          description: Number of hours to analyze (1-720 for up to 30 days, default 24)
          schema:
            type: integer
            minimum: 1
            maximum: 720
            default: 24
            example: 24
      responses:
        '200':
          description: Widget timeline data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WidgetTimelinePoint'
        '404':
          description: Widget endpoints disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /ip/search:
    get:
      tags:
        - IP Analytics
      summary: Search for IP addresses
      description: Search for IP addresses by partial match with basic statistics
      operationId: searchIPs
      parameters:
        - name: q
          in: query
          description: IP address search query (partial match supported)
          required: true
          schema:
            type: string
          example: 192.168
        - name: limit
          in: query
          description: Maximum number of results (1-100, default 10)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        '200':
          description: List of matching IP addresses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IPSearchResult'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /ip/{ip}/stats:
    get:
      tags:
        - IP Analytics
      summary: Get detailed statistics for a specific IP
      description: Returns comprehensive statistics including request counts, bandwidth, geographic data, and ASN information
      operationId: getIPDetailedStats
      parameters:
        - name: ip
          in: path
          description: IP address to analyze
          required: true
          schema:
            type: string
          example: 192.168.1.100
      responses:
        '200':
          description: Detailed IP statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IPDetailedStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /ip/{ip}/timeline:
    get:
      tags:
        - IP Analytics
      summary: Get timeline statistics for a specific IP
      description: Returns time-series data for requests from the specified IP address
      operationId: getIPTimeline
      parameters:
        - name: ip
          in: path
          description: IP address to analyze
          required: true
          schema:
            type: string
          example: 192.168.1.100
        - name: hours
          in: query
          description: Number of hours to look back (1-8760, default 168)
          schema:
            type: integer
            minimum: 1
            maximum: 8760
            default: 168
      responses:
        '200':
          description: Timeline data for the IP
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimelineData'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /ip/{ip}/heatmap:
    get:
      tags:
        - IP Analytics
      summary: Get traffic heatmap for a specific IP
      description: Returns hourly traffic data grouped by day of week for the specified IP address
      operationId: getIPTrafficHeatmap
      parameters:
        - name: ip
          in: path
          description: IP address to analyze
          required: true
          schema:
            type: string
          example: 192.168.1.100
        - name: days
          in: query
          description: Number of days to analyze (1-365, default 30)
          schema:
            type: integer
            minimum: 1
            maximum: 365
            default: 30
      responses:
        '200':
          description: Traffic heatmap data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrafficHeatmapData'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /ip/{ip}/top/paths:
    get:
      tags:
        - IP Analytics
      summary: Get top paths accessed by a specific IP
      description: Returns most accessed paths by the specified IP address
      operationId: getIPTopPaths
      parameters:
        - name: ip
          in: path
          description: IP address to analyze
          required: true
          schema:
            type: string
          example: 192.168.1.100
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Top paths for the IP
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PathStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /ip/{ip}/top/backends:
    get:
      tags:
        - IP Analytics
      summary: Get top backends accessed by a specific IP
      description: Returns backend services most accessed by the specified IP address
      operationId: getIPTopBackends
      parameters:
        - name: ip
          in: path
          description: IP address to analyze
          required: true
          schema:
            type: string
          example: 192.168.1.100
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Top backends for the IP
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BackendStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /ip/{ip}/distribution/status-codes:
    get:
      tags:
        - IP Analytics
      summary: Get status code distribution for a specific IP
      description: Returns distribution of HTTP status codes for requests from the specified IP address
      operationId: getIPStatusCodeDistribution
      parameters:
        - name: ip
          in: path
          description: IP address to analyze
          required: true
          schema:
            type: string
          example: 192.168.1.100
      responses:
        '200':
          description: Status code distribution
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StatusCodeStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /ip/{ip}/top/browsers:
    get:
      tags:
        - IP Analytics
      summary: Get top browsers used by a specific IP
      description: Returns most common browsers used by the specified IP address
      operationId: getIPTopBrowsers
      parameters:
        - name: ip
          in: path
          description: IP address to analyze
          required: true
          schema:
            type: string
          example: 192.168.1.100
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Top browsers for the IP
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BrowserStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /ip/{ip}/top/operating-systems:
    get:
      tags:
        - IP Analytics
      summary: Get top operating systems used by a specific IP
      description: Returns most common operating systems used by the specified IP address
      operationId: getIPTopOperatingSystems
      parameters:
        - name: ip
          in: path
          description: IP address to analyze
          required: true
          schema:
            type: string
          example: 192.168.1.100
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Top operating systems for the IP
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OSStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /ip/{ip}/distribution/device-types:
    get:
      tags:
        - IP Analytics
      summary: Get device type distribution for a specific IP
      description: Returns distribution of device types (desktop, mobile, tablet, bot) for the specified IP address
      operationId: getIPDeviceTypeDistribution
      parameters:
        - name: ip
          in: path
          description: IP address to analyze
          required: true
          schema:
            type: string
          example: 192.168.1.100
      responses:
        '200':
          description: Device type distribution
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeviceTypeStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /ip/{ip}/performance/response-time:
    get:
      tags:
        - IP Analytics
      summary: Get response time statistics for a specific IP
      description: Returns response time metrics including min, max, avg, and percentiles for requests from the specified IP address
      operationId: getIPResponseTimeStats
      parameters:
        - name: ip
          in: path
          description: IP address to analyze
          required: true
          schema:
            type: string
          example: 192.168.1.100
      responses:
        '200':
          description: Response time statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseTimeStats'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /ip/{ip}/recent-requests:
    get:
      tags:
        - IP Analytics
      summary: Get recent requests from a specific IP
      description: Returns the most recent HTTP requests from the specified IP address with full details
      operationId: getIPRecentRequests
      parameters:
        - name: ip
          in: path
          description: IP address to analyze
          required: true
          schema:
            type: string
          example: 192.168.1.100
        - name: limit
          in: query
          description: Maximum number of results (1-250, default 25)
          schema:
            type: integer
            minimum: 1
            maximum: 250
            default: 25
      responses:
        '200':
          description: Recent requests from the IP
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HTTPRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  parameters:
    # Legacy service filter (backward compatible)
    HostFilter:
      name: host
      in: query
      description: |
        **Legacy parameter** - Filter results by backend/service name.
        Equivalent to using `service` parameter with `service_type=auto`.
        Kept for backward compatibility with older clients.
      required: false
      schema:
        type: string
      example: my-service

    # New single service filtering
    ServiceFilter:
      name: service
      in: query
      description: Service name to filter by (backend name, URL, or host depending on service_type)
      required: false
      schema:
        type: string
      example: api-service

    ServiceTypeFilter:
      name: service_type
      in: query
      description: |
        Type of service identifier to use for filtering:
        - `auto` (default): Automatically detects and uses backend_name, backend_url, or host based on availability
        - `backend_name`: Filter specifically by Traefik backend name
        - `backend_url`: Filter by backend URL
        - `host`: Filter by HTTP Host header
      required: false
      schema:
        type: string
        enum: [auto, backend_name, backend_url, host]
        default: auto
      example: backend_name

    # Multi-service filtering (arrays)
    ServicesArray:
      name: services[]
      in: query
      description: |
        Array of service names for multi-service filtering.
        Must be used together with `service_types[]` parameter with matching array length.
        Can be repeated multiple times: `?services[]=api&services[]=web`
      required: false
      schema:
        type: array
        items:
          type: string
      style: form
      explode: true
      example: [api-service, web-frontend]

    ServiceTypesArray:
      name: service_types[]
      in: query
      description: |
        Array of service types corresponding to `services[]` parameter.
        Must have the same length as `services[]` array.
        Each element can be: auto, backend_name, backend_url, or host
      required: false
      schema:
        type: array
        items:
          type: string
          enum: [auto, backend_name, backend_url, host]
      style: form
      explode: true
      example: [backend_name, host]

    # Hide My Traffic parameters
    ExcludeOwnIP:
      name: exclude_own_ip
      in: query
      description: |
        Set to `true` to exclude requests from your own IP address.
        The server automatically detects your IP from the request.
        When `true` without `exclude_services[]`, excludes your IP from ALL services.
      required: false
      schema:
        type: boolean
        default: false
      example: true

    ExcludeServices:
      name: exclude_services[]
      in: query
      description: |
        Array of service names to exclude your IP from (used with `exclude_own_ip=true`).
        If omitted, your IP is excluded from all services.
        If specified, your IP is only excluded from the listed services.
        Must be used together with `exclude_service_types[]`.
      required: false
      schema:
        type: array
        items:
          type: string
      style: form
      explode: true
      example: [admin-panel, internal-api]

    ExcludeServiceTypes:
      name: exclude_service_types[]
      in: query
      description: |
        Array of service types corresponding to `exclude_services[]`.
        Must have the same length as `exclude_services[]` array.
      required: false
      schema:
        type: array
        items:
          type: string
          enum: [auto, backend_name, backend_url, host]
      style: form
      explode: true
      example: [backend_name, host]

    # Common parameters
    LimitParam:
      name: limit
      in: query
      description: Maximum number of results (1-100, default 10)
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10

    LimitParam1000:
      name: limit
      in: query
      description: Maximum number of results (1-1000, default 100)
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 100

    OffsetParam:
      name: offset
      in: query
      description: Pagination offset (number of items to skip)
      schema:
        type: integer
        minimum: 0
        default: 0

    HoursParam:
      name: hours
      in: query
      description: Number of hours to look back (1-8760 for up to 1 year, 0 for all time, default 168 for 7 days)
      schema:
        type: integer
        minimum: 0
        maximum: 8760
        default: 168
        example: 168

    DaysParam:
      name: days
      in: query
      description: Number of days to analyze (1-365, default 30)
      schema:
        type: integer
        minimum: 1
        maximum: 365
        default: 30

  schemas:
    StatsSummary:
      type: object
      properties:
        total_requests:
          type: integer
          format: int64
          description: Total number of requests
          example: 125643
        valid_requests:
          type: integer
          format: int64
          description: Number of successful requests (2xx, 3xx)
          example: 119234
        failed_requests:
          type: integer
          format: int64
          description: Number of failed requests (4xx, 5xx)
          example: 6409
        unique_visitors:
          type: integer
          format: int64
          description: Number of unique IP addresses
          example: 1523
        unique_files:
          type: integer
          format: int64
          description: Number of unique paths accessed
          example: 342
        unique_404:
          type: integer
          format: int64
          description: Number of unique 404 paths
          example: 23
        total_bandwidth:
          type: integer
          format: int64
          description: Total bandwidth in bytes
          example: 5368709120
        avg_response_time:
          type: number
          format: double
          description: Average response time in milliseconds
          example: 142.5
        success_rate:
          type: number
          format: double
          description: Success rate percentage (0-100)
          example: 94.9
        not_found_rate:
          type: number
          format: double
          description: 404 error rate percentage
          example: 3.2
        server_error_rate:
          type: number
          format: double
          description: 5xx error rate percentage
          example: 1.9
        requests_per_hour:
          type: number
          format: double
          description: Average requests per hour
          example: 745.3
        top_country:
          type: string
          description: Country code with most traffic
          example: "US"
        top_path:
          type: string
          description: Most accessed path
          example: "/api/v1/users"

    TimelineData:
      type: object
      properties:
        hour:
          type: string
          format: date-time
          description: Timestamp for this data point
          example: "2025-11-03T14:00:00Z"
        requests:
          type: integer
          format: int64
          description: Number of requests in this hour
          example: 1234
        unique_visitors:
          type: integer
          format: int64
          description: Unique visitors in this hour
          example: 89
        bandwidth:
          type: integer
          format: int64
          description: Bandwidth in bytes for this hour
          example: 52428800
        avg_response_time:
          type: number
          format: double
          description: Average response time in milliseconds
          example: 125.3

    StatusCodeTimelineData:
      type: object
      properties:
        hour:
          type: string
          format: date-time
          example: "2025-11-03T14:00:00Z"
        status_2xx:
          type: integer
          format: int64
          description: Count of 2xx responses
          example: 1100
        status_3xx:
          type: integer
          format: int64
          description: Count of 3xx responses
          example: 50
        status_4xx:
          type: integer
          format: int64
          description: Count of 4xx responses
          example: 75
        status_5xx:
          type: integer
          format: int64
          description: Count of 5xx responses
          example: 9

    TrafficHeatmapData:
      type: object
      properties:
        day_of_week:
          type: integer
          description: Day of week (0=Sunday, 6=Saturday)
          minimum: 0
          maximum: 6
          example: 1
        hour:
          type: integer
          description: Hour of day (0-23)
          minimum: 0
          maximum: 23
          example: 14
        requests:
          type: integer
          format: int64
          description: Number of requests
          example: 523
        avg_response_time:
          type: number
          format: double
          description: Average response time in milliseconds
          example: 134.2

    PathStats:
      type: object
      properties:
        path:
          type: string
          description: URL path
          example: "/api/v1/stats/summary"
        hits:
          type: integer
          format: int64
          description: Number of requests to this path
          example: 5432
        unique_visitors:
          type: integer
          format: int64
          description: Unique visitors to this path
          example: 234
        avg_response_time:
          type: number
          format: double
          description: Average response time in milliseconds
          example: 89.3
        total_bandwidth:
          type: integer
          format: int64
          description: Total bandwidth in bytes
          example: 10485760

    CountryStats:
      type: object
      properties:
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: "US"
        country_name:
          type: string
          description: Full country name
          example: "United States"
        hits:
          type: integer
          format: int64
          description: Number of requests from this country
          example: 15234
        unique_visitors:
          type: integer
          format: int64
          description: Unique visitors from this country
          example: 892
        bandwidth:
          type: integer
          format: int64
          description: Total bandwidth in bytes
          example: 268435456

    IPStats:
      type: object
      properties:
        ip_address:
          type: string
          format: ipv4
          description: IP address
          example: "192.168.1.100"
        country:
          type: string
          description: Country code
          example: "US"
        city:
          type: string
          description: City name
          example: "New York"
        latitude:
          type: number
          format: double
          description: Latitude coordinate
          example: 40.7128
        longitude:
          type: number
          format: double
          description: Longitude coordinate
          example: -74.0060
        hits:
          type: integer
          format: int64
          description: Number of requests from this IP
          example: 234
        bandwidth:
          type: integer
          format: int64
          description: Total bandwidth in bytes
          example: 5242880

    StatusCodeStats:
      type: object
      properties:
        status_code:
          type: integer
          description: HTTP status code
          example: 200
        count:
          type: integer
          format: int64
          description: Number of requests with this status code
          example: 98765

    MethodStats:
      type: object
      properties:
        method:
          type: string
          description: HTTP method
          example: "GET"
        count:
          type: integer
          format: int64
          description: Number of requests using this method
          example: 112345

    ProtocolStats:
      type: object
      properties:
        protocol:
          type: string
          description: HTTP protocol version
          example: "HTTP/2.0"
        count:
          type: integer
          format: int64
          description: Number of requests using this protocol
          example: 85432

    TLSVersionStats:
      type: object
      properties:
        tls_version:
          type: string
          description: TLS version
          example: "TLS 1.3"
        count:
          type: integer
          format: int64
          description: Number of requests using this TLS version
          example: 95123

    UserAgentStats:
      type: object
      properties:
        user_agent:
          type: string
          description: User agent string
          example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
        count:
          type: integer
          format: int64
          description: Number of requests with this user agent
          example: 2345

    BrowserStats:
      type: object
      properties:
        browser:
          type: string
          description: Browser name
          example: "Chrome"
        count:
          type: integer
          format: int64
          description: Number of requests from this browser
          example: 67890

    OSStats:
      type: object
      properties:
        os:
          type: string
          description: Operating system name
          example: "Windows 10"
        count:
          type: integer
          format: int64
          description: Number of requests from this OS
          example: 45678

    DeviceTypeStats:
      type: object
      properties:
        device_type:
          type: string
          description: Device type
          enum: [desktop, mobile, tablet, bot, unknown]
          example: "desktop"
        count:
          type: integer
          format: int64
          description: Number of requests from this device type
          example: 78901

    ReferrerStats:
      type: object
      properties:
        referrer:
          type: string
          description: Full referrer URL
          example: "https://google.com/search"
        hits:
          type: integer
          format: int64
          description: Number of requests from this referrer
          example: 1234
        unique_visitors:
          type: integer
          format: int64
          description: Unique visitors from this referrer
          example: 567

    ReferrerDomainStats:
      type: object
      properties:
        domain:
          type: string
          description: Referrer domain
          example: "google.com"
        hits:
          type: integer
          format: int64
          description: Total hits from this domain
          example: 5678
        unique_visitors:
          type: integer
          format: int64
          description: Unique visitors from this domain
          example: 1234

    BackendStats:
      type: object
      properties:
        backend_name:
          type: string
          description: Backend service name
          example: "api-service-prod"
        backend_url:
          type: string
          description: Backend URL
          example: "http://api-service:8080"
        hits:
          type: integer
          format: int64
          description: Number of requests to this backend
          example: 12345
        bandwidth:
          type: integer
          format: int64
          description: Total bandwidth in bytes
          example: 536870912
        avg_response_time:
          type: number
          format: double
          description: Average response time in milliseconds
          example: 95.7
        error_count:
          type: integer
          format: int64
          description: Number of errors from this backend
          example: 23

    ASNStats:
      type: object
      properties:
        asn:
          type: integer
          description: Autonomous System Number
          example: 15169
        asn_org:
          type: string
          description: Organization name
          example: "Google LLC"
        hits:
          type: integer
          format: int64
          description: Number of requests from this ASN
          example: 8765
        bandwidth:
          type: integer
          format: int64
          description: Total bandwidth in bytes
          example: 104857600
        country:
          type: string
          description: Country code
          example: "US"

    ResponseTimeStats:
      type: object
      properties:
        min:
          type: number
          format: double
          description: Minimum response time in milliseconds
          example: 12.5
        max:
          type: number
          format: double
          description: Maximum response time in milliseconds
          example: 2345.8
        avg:
          type: number
          format: double
          description: Average response time in milliseconds
          example: 142.3
        p50:
          type: number
          format: double
          description: 50th percentile (median) in milliseconds
          example: 98.5
        p95:
          type: number
          format: double
          description: 95th percentile in milliseconds
          example: 345.2
        p99:
          type: number
          format: double
          description: 99th percentile in milliseconds
          example: 567.9

    LogProcessingStats:
      type: object
      description: Log file processing progress information with intelligent percentage calculation
      properties:
        log_source_name:
          type: string
          description: Name of the log source being processed
          example: "traefik-access-logs"
        file_size:
          type: integer
          format: int64
          description: Total file size in bytes (current size, may grow during processing)
          example: 1073741824
        bytes_processed:
          type: integer
          format: int64
          description: Number of bytes read from the file so far (updates every 500ms during active processing)
          example: 536870912
        percentage:
          type: number
          format: double
          description: |
            Processing progress percentage (0-100). Intelligently calculated using:
            - Record-based estimation: avg bytes per record × estimated total records
            - Byte-based fallback: bytes_processed / file_size × 100
            - Capped at 100% even if file grows during processing
          example: 50.0
        last_processed_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of last processing update (updates every 500ms during active processing)
          example: "2025-11-06T10:30:15Z"

    HTTPRequest:
      type: object
      description: Individual HTTP request record
      properties:
        id:
          type: integer
          format: int64
          example: 12345
        timestamp:
          type: string
          format: date-time
          example: "2025-11-03T14:32:15Z"
        client_ip:
          type: string
          example: "192.168.1.100"
        method:
          type: string
          example: "GET"
        path:
          type: string
          example: "/api/v1/users"
        status_code:
          type: integer
          example: 200
        response_time:
          type: number
          format: double
          description: Response time in milliseconds
          example: 45.2
        bytes_sent:
          type: integer
          format: int64
          description: Response size in bytes
          example: 2048
        referer:
          type: string
          example: "https://example.com"
        user_agent:
          type: string
          example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
        country:
          type: string
          description: ISO country code
          example: "US"
        city:
          type: string
          example: "New York"
        browser:
          type: string
          example: "Chrome"
        os:
          type: string
          example: "Windows 10"
        device_type:
          type: string
          example: "desktop"
        backend_name:
          type: string
          example: "api-service-prod"

    RealtimeMetrics:
      type: object
      description: Real-time metrics snapshot
      properties:
        request_rate:
          type: number
          format: double
          description: Current requests per second
          example: 45.3
        error_rate:
          type: number
          format: double
          description: Error rate (errors per second)
          example: 2.3
        avg_response_time:
          type: number
          format: double
          description: Average response time (ms)
          example: 89.5
        active_connections:
          type: integer
          description: Number of active connections
          example: 123
        status_2xx:
          type: integer
          format: int64
          description: Count of 2xx status codes
          example: 150
        status_4xx:
          type: integer
          format: int64
          description: Count of 4xx status codes
          example: 5
        status_5xx:
          type: integer
          format: int64
          description: Count of 5xx status codes
          example: 1
        timestamp:
          type: string
          format: date-time
          example: "2025-11-03T14:32:15Z"
        top_ips:
          type: array
          description: Top IPs by request rate
          items:
            $ref: '#/components/schemas/IPMetrics'
        latest_requests:
          type: array
          description: List of most recent requests
          items:
            $ref: '#/components/schemas/RequestSummary'
        per_service:
          type: array
          description: Metrics per service
          items:
            $ref: '#/components/schemas/ServiceMetrics'

    IPMetrics:
      type: object
      description: Metrics for a specific IP address
      properties:
        ip:
          type: string
          format: ipv4
          example: "192.168.1.100"
        country:
          type: string
          description: ISO country code
          example: "US"
        request_rate:
          type: number
          format: double
          description: Requests per second
          example: 12.5

    RequestSummary:
      type: object
      description: Lightweight summary of a request
      properties:
        id:
          type: integer
          format: int64
          example: 12345
        timestamp:
          type: string
          format: date-time
          example: "2025-11-03T14:32:15Z"
        method:
          type: string
          example: "GET"
        host:
          type: string
          example: "api.example.com"
        backend_name:
          type: string
          example: "api-service"
        path:
          type: string
          example: "/api/v1/users"
        status_code:
          type: integer
          example: 200
        response_time_ms:
          type: number
          format: double
          example: 45.2
        geo_country:
          type: string
          example: "US"
        client_ip:
          type: string
          example: "192.168.1.100"

    ServiceMetrics:
      type: object
      description: Metrics for a specific service/backend
      properties:
        service_name:
          type: string
          example: "api-service-prod"
        request_rate:
          type: number
          format: double
          description: Requests per second
          example: 23.4

    DomainStats:
      type: object
      deprecated: true
      description: "DEPRECATED: Use ServiceInfo instead"
      properties:
        domain:
          type: string
          description: Domain/service name (from backend_name field only)
          example: my-service
        request_count:
          type: integer
          format: int64
          description: Total requests for this domain
          example: 12345

    ServiceInfo:
      type: object
      description: Service information with type identification and request count
      properties:
        name:
          type: string
          description: Service name (backend name, URL, or host depending on type)
          example: api-service-prod
        type:
          type: string
          enum: [backend_name, backend_url, host]
          description: |
            Type of service identifier:
            - `backend_name`: Traefik backend name (highest priority)
            - `backend_url`: Backend URL
            - `host`: HTTP Host header (lowest priority)
          example: backend_name
        count:
          type: integer
          format: int64
          description: Total number of requests for this service
          example: 12345

    IPDetailedStats:
      type: object
      description: Comprehensive statistics for a specific IP address
      properties:
        ip_address:
          type: string
          format: ipv4
          description: IP address
          example: "192.168.1.100"
        total_requests:
          type: integer
          format: int64
          description: Total number of requests from this IP
          example: 1234
        first_seen:
          type: string
          format: date-time
          description: First time this IP was seen
          example: "2025-10-15T08:23:45Z"
        last_seen:
          type: string
          format: date-time
          description: Last time this IP was seen
          example: "2025-11-03T14:32:15Z"
        geo_country:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: "US"
        geo_city:
          type: string
          description: City name
          example: "New York"
        geo_lat:
          type: number
          format: double
          description: Latitude coordinate
          example: 40.7128
        geo_lon:
          type: number
          format: double
          description: Longitude coordinate
          example: -74.0060
        asn:
          type: integer
          description: Autonomous System Number
          example: 15169
        asn_org:
          type: string
          description: Organization name
          example: "Google LLC"
        total_bandwidth:
          type: integer
          format: int64
          description: Total bandwidth in bytes
          example: 52428800
        avg_response_time:
          type: number
          format: double
          description: Average response time in milliseconds
          example: 145.3
        success_rate:
          type: number
          format: double
          description: Success rate percentage (0-100)
          example: 95.5
        error_rate:
          type: number
          format: double
          description: Error rate percentage (0-100)
          example: 4.5
        unique_backends:
          type: integer
          format: int64
          description: Number of unique backends accessed
          example: 5
        unique_paths:
          type: integer
          format: int64
          description: Number of unique paths accessed
          example: 42

    IPSearchResult:
      type: object
      description: Basic IP information for search results
      properties:
        ip_address:
          type: string
          format: ipv4
          description: IP address
          example: "192.168.1.100"
        hits:
          type: integer
          format: int64
          description: Number of requests from this IP
          example: 234
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: "US"
        city:
          type: string
          description: City name
          example: "New York"
        last_seen:
          type: string
          format: date-time
          description: Last time this IP was seen
          example: "2025-11-03T14:32:15Z"

    WidgetRealtimeData:
      type: object
      description: Compact real-time metrics for widget embedding
      properties:
        status:
          type: string
          description: System health status
          enum: [healthy, warning, danger, error]
          example: "healthy"
        requests_per_minute:
          type: number
          format: double
          description: Requests per minute (calculated from last hour)
          example: 125.5
        error_rate:
          type: number
          format: double
          description: Combined error rate percentage (4xx + 5xx)
          example: 2.5
        avg_response_time:
          type: number
          format: double
          description: Average response time in milliseconds
          example: 145.3
        unique_ips:
          type: integer
          format: int64
          description: Number of unique IP addresses in the last hour
          example: 1523

    WidgetSummaryData:
      type: object
      description: Compact summary statistics for widget embedding
      properties:
        status:
          type: string
          description: System health status
          enum: [healthy, warning, danger, error]
          example: "healthy"
        total_requests:
          type: integer
          format: int64
          description: Total number of requests in the time period
          example: 125643
        requests_per_hr:
          type: number
          format: double
          description: Average requests per hour
          example: 5235.1
        error_rate:
          type: number
          format: double
          description: Combined error rate percentage (4xx + 5xx)
          example: 2.5
        avg_response_ms:
          type: number
          format: double
          description: Average response time in milliseconds
          example: 145.3
        unique_ips:
          type: integer
          format: int64
          description: Number of unique IP addresses
          example: 15234
        bandwidth_mb:
          type: number
          format: double
          description: Total bandwidth in megabytes
          example: 5123.5

    WidgetTimelinePoint:
      type: object
      description: Single point in widget timeline data
      properties:
        hour:
          type: string
          format: date-time
          description: Timestamp of this data point
          example: "2025-11-03T14:00:00Z"
        requests:
          type: integer
          format: int64
          description: Number of requests in this time bucket
          example: 1523

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: "Failed to retrieve data"

  responses:
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'