apache / apache/flagon

feat(schema): restructure log output format to match proto schema

Open
#143 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

Change the default JSON wire format to align with the proto schema structure. This is the primary breaking change in v3.0.0.

## Current Format (v2.x — flat)

```json
{
"target": "button#submit",
"pageUrl": "https://example.com",
"userAgent": "Mozilla/5.0...",
"clientTime": 1720800000000,
"type": "click",
"logType": "raw",
"userId": "user123",
"sessionId": "sess-abc",
"attributes": { "data-count": 5 }
}
```

## New Format (v3.0 — proto-aligned)

```json
{
"metadata": {
"pageUrl": "https://example.com",
"userAgent": "Mozilla/5.0...",
"clientTime": 1720800000000,
"userId": "user123",
"sessionId": "sess-abc",
"screenResolution": { "width": 1920, "height": 1080 }
},
"target": "button#submit",
"eventType": "click",
"userAction": true,
"attributes": { "data-count": "5" }
}
```

## Key Changes

- Shared fields grouped under `metadata` object
- `type` → `eventType`
- `scrnRes` → `screenResolution` (inside metadata)
- `attributes` values are always strings (no `JSON.parse`)
- `logType` field moves to envelope level

## Depends On

- #142 (wire proto types into packageLogs)
- #139 (LogExporter interface — enables legacy format fallback)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the packageLogs work described in #142 and the LogExporter interface from #139, then compare the current and proto-aligned JSON examples. Done means the default format uses the metadata grouping, renamed fields, string attributes, and envelope-level logType while retaining the legacy fallback.

Written by the indexing model from the issue text.

Assessment

Domain
backend-api-design
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.