Troubleshooting

Enable Cross-Origin Resource Sharing (CORS)

Logs generated by Apache Flagon UserALE.js are sent from the browser to your configured collector endpoint (url or otlpEndpoint). Because browser security policies enforce CORS on cross-origin fetch() requests (especially when Content-Type: application/json, Authorization, x-api-key, or traceparent headers are sent), your collector must allow the application’s origin and headers.

OpenTelemetry Collector CORS Configuration (receivers.otlp.protocols.http)

When exporting directly from the browser to an OpenTelemetry Collector (exporterType: 'otlp'), enable cors on the HTTP receiver in your otel-collector-config.yaml:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
        cors:
          allowed_origins:
            - "http://localhost:*"
            - "https://your-app.example.com"
          allowed_headers:
            - "Content-Type"
            - "Authorization"
            - "x-api-key"
            - "traceparent"
            - "tracestate"

See products/userale/example/otel-demo/otel-collector-config.yaml for a complete working example.

Page Unload (pagehide) Payload Limits

Browsers enforce a 64 KiB cumulative quota on fetch(..., { keepalive: true }) requests triggered during pagehide (tab close or navigation). UserALE.js’s HTTP exporters (HttpJsonExporter, ProtoJsonExporter, OtlpJsonExporter) automatically split large unload queues into <= 48 KiB chunks via chunkLogsForKeepalive so unload flushes preserve custom Authorization and x-api-key headers without exceeding browser keepalive limits.

Contributing

Contributions are welcome! See our Contributing Guide or open an issue on GitHub.