apache / apache/flagon

feat(export): OTLP/JSON exporter for OpenTelemetry integration

Open
#140 0 comments 0 reactions 0 assignees View on GitHub
enhancement Userale
Dominant language
Jupyter Notebook
Stars
30
Forks
15
PR merge metrics
No merged PRs in 30d

Description

## Summary

Implement an `OtlpJsonExporter` that sends UserALE logs to any OpenTelemetry Collector via OTLP/HTTP JSON.

## Motivation

OpenTelemetry is the de-facto standard for observability. OTLP support lets Flagon users send behavioral data to Grafana, Datadog, Jaeger, and any OTel-compatible backend — without building custom ingestion pipelines.

No competing behavioral analytics library (PostHog, Matomo, Plausible) speaks OTLP. This is a differentiation opportunity.

## Design

- Maps Flagon log fields → OTLP `LogRecord` attributes using OTel semantic conventions
- Builds OTLP/JSON payloads using plain objects (zero external dependencies)
- Ships to standard OTLP HTTP receiver (port 4318, `/v1/logs`)
- ~150 lines of code, ~2-3 KB gzipped added to bundle

## Attribute Mapping

| Flagon Field | OTLP Mapping |
|---|---|
| `clientTime` | `timeUnixNano` |
| `toolName` | `resource.service.name` |
| `useraleVersion` | `resource.telemetry.sdk.version` |
| `userId` | `attributes.enduser.id` |
| `sessionId` | `attributes.session.id` |
| `pageUrl` | `attributes.url.full` |
| `target` | `attributes.flagon.dom.target` |
| `type` | `attributes.flagon.event_type` |
| `logType` | `attributes.flagon.log_type` |
| `details` | `body` (JSON string) |

## User Experience

```javascript
// One config change to enable OTLP
userale.start({
exporterType: 'otlp',
otlpEndpoint: 'http://localhost:4318',
});
```

## Depends On

- #139 (LogExporter interface)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the LogExporter interface from #139 and the userale.start configuration entry point shown in the issue. Trace how exporterType and otlpEndpoint are handled, then implement the documented Flagon-to-OTLP mappings and verify that logs reach the standard /v1/logs endpoint with the specified JSON structure.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
observability
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.