The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
more screenshots and diagrams
ddux8b18d472d941
diff --git a/.github/screenshots/endpoints.png b/.github/screenshots/endpoints.pngnew file mode 100644index 00000000..bcd55dbeBinary files /dev/null and b/.github/screenshots/endpoints.png differdiff --git a/.github/screenshots/issues.png b/.github/screenshots/issues.pngnew file mode 100644index 00000000..be01e856Binary files /dev/null and b/.github/screenshots/issues.png differdiff --git a/.github/screenshots/logs.png b/.github/screenshots/logs.pngnew file mode 100644index 00000000..52c981ebBinary files /dev/null and b/.github/screenshots/logs.png differdiff --git a/.github/screenshots/metrics.png b/.github/screenshots/metrics.pngnew file mode 100644index 00000000..4119c8feBinary files /dev/null and b/.github/screenshots/metrics.png differdiff --git a/.github/screenshots/span-waterfall.png b/.github/screenshots/span-waterfall.pngnew file mode 100644index 00000000..d08c8468Binary files /dev/null and b/.github/screenshots/span-waterfall.png differdiff --git a/README.md b/README.mdindex 8e265795..3550c2cf 100644--- a/README.md+++ b/README.md@@ -29,7 +29,12 @@ Traceway is an **OpenTelemetry-native** observability platform that combines **l**MIT licensed. No BSL. No "open core."** Every feature is in the box. Self-host it for free, or run it on [Traceway Cloud](https://cloud.tracewayapp.com) if you'd rather not babysit infra.-<img alt="Traceway Dashboard" src="./website/public/images/performance-endpoints-impact-table.png" />+<table width="100%">+<tr>+<td width="50%" valign="top"><img alt="Traceway Issues" src="./.github/screenshots/issues.png" /></td>+<td width="50%" valign="top"><img alt="Traceway Endpoints" src="./.github/screenshots/endpoints.png" /></td>+</tr>+</table><p align="center"><a href="https://discord.gg/RZq9NT62nc"><b>π Join the Traceway Community on Discord β</b></a><br>@@ -205,12 +210,12 @@ Traceway integrates with the tools you already use. Every integration ships trac<table width="100%"><tr>-<td width="50%" valign="top"><b>Logs β trace-linked search</b><br><img src="./website/public/images/logs-search-and-detail.png" alt="Logs" /></td>-<td width="50%" valign="top"><b>Span waterfall</b><br><img src="./website/public/images/traces-spans-waterfall.png" alt="Spans" /></td>+<td width="50%" valign="top"><b>Logs β trace-linked search</b><br><img src="./.github/screenshots/logs.png" alt="Logs" /></td>+<td width="50%" valign="top"><b>Span waterfall</b><br><img src="./.github/screenshots/span-waterfall.png" alt="Spans" /></td></tr><tr>-<td width="50%" valign="top"><b>Metrics β application dashboard</b><br><img src="./website/public/images/metrics-application-dashboard.png" alt="Metrics" /></td>-<td width="50%" valign="top"><b>Exceptions β grouped & ranked</b><br><img src="./website/public/images/exceptions-grouped-ranked.png" alt="Exceptions" /></td>+<td width="50%" valign="top"><b>Metrics β application dashboard</b><br><img src="./.github/screenshots/metrics.png" alt="Metrics" /></td>+<td width="50%" valign="top"><b>Exceptions β grouped & ranked</b><br><img src="./.github/screenshots/issues.png" alt="Exceptions" /></td></tr></table>diff --git a/diagrams/architecture-diagram.drawio b/diagrams/architecture-diagram.drawioindex d3147e2c..449365ca 100644--- a/diagrams/architecture-diagram.drawio+++ b/diagrams/architecture-diagram.drawio@@ -1,71 +1,110 @@<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36" version="29.3.6"><diagram name="Page-1" id="wy32oRJBnUYnc9i8Ji1n">- <mxGraphModel dx="815" dy="558" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">+ <mxGraphModel dx="815" dy="558" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0" adaptiveColors="auto"><root><mxCell id="0" /><mxCell id="1" parent="0" />- <mxCell id="nGLuf51OtG82o4zcJS6--42" edge="1" parent="1" source="nGLuf51OtG82o4zcJS6--3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" target="nGLuf51OtG82o4zcJS6--21">- <mxGeometry relative="1" as="geometry" />+ <mxCell id="dt-1" parent="1" style="rounded=0;whiteSpace=wrap;html=1;dashed=1;verticalAlign=top;align=center;spacingTop=2;fontSize=11;" value="<b>Distributed Trace</b> &nbsp;<i>traces from any service that share a distributedTraceId are grouped together</i>" vertex="1">+ <mxGeometry height="150" width="640" x="105" y="40" as="geometry" /></mxCell>- <mxCell id="nGLuf51OtG82o4zcJS6--48" edge="1" parent="1" source="nGLuf51OtG82o4zcJS6--3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" target="nGLuf51OtG82o4zcJS6--46">- <mxGeometry relative="1" as="geometry" />+ <mxCell id="trace-1" parent="1" style="swimlane;whiteSpace=wrap;html=1;expand=1;collapsible=0;" value="Trace" vertex="1">+ <mxGeometry height="103" width="450" x="200" y="70" as="geometry" />+ </mxCell>+ <mxCell id="trace-2" parent="trace-1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Endpoint</b><br><i>GET /users/:id</i>" vertex="1">+ <mxGeometry height="60" width="135" x="11" y="31" as="geometry" />+ </mxCell>+ <mxCell id="trace-3" parent="trace-1" style="rounded=0;whiteSpace=wrap;html=1;spacing=2;" value="<b>Task</b><br><i>send-notifications</i>" vertex="1">+ <mxGeometry height="60" width="135" x="157" y="31" as="geometry" /></mxCell>- <mxCell id="nGLuf51OtG82o4zcJS6--3" parent="1" style="swimlane;whiteSpace=wrap;html=1;expand=1;collapsible=0;" value="Trace" vertex="1">- <mxGeometry height="103" width="270" x="186" y="79" as="geometry" />+ <mxCell id="trace-4" parent="trace-1" style="rounded=0;whiteSpace=wrap;html=1;spacing=2;" value="<b>AI Trace</b><br><i>chat claude-sonnet-5</i>" vertex="1">+ <mxGeometry height="60" width="135" x="303" y="31" as="geometry" /></mxCell>- <mxCell id="nGLuf51OtG82o4zcJS6--4" parent="nGLuf51OtG82o4zcJS6--3" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Endpoint</b><br><i>GET /users/:id</i>" vertex="1">+ <mxCell id="issue-1" parent="1" style="swimlane;whiteSpace=wrap;html=1;expand=1;collapsible=0;" value="Issue" vertex="1">+ <mxGeometry height="103" width="270" x="30" y="330" as="geometry" />+ </mxCell>+ <mxCell id="issue-2" parent="issue-1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Exception</b><br><i>db failed to open</i>" vertex="1"><mxGeometry height="60" width="120" x="11" y="31" as="geometry" /></mxCell>- <mxCell id="nGLuf51OtG82o4zcJS6--6" parent="nGLuf51OtG82o4zcJS6--3" style="rounded=0;whiteSpace=wrap;html=1;spacing=2;" value="<b>Task</b><br><i>send-notifications</i>" vertex="1">+ <mxCell id="issue-3" parent="issue-1" style="rounded=0;whiteSpace=wrap;html=1;spacing=2;" value="<b>Message</b><br><i>captured log text</i>" vertex="1"><mxGeometry height="60" width="120" x="139" y="31" as="geometry" /></mxCell>- <mxCell id="nGLuf51OtG82o4zcJS6--41" edge="1" parent="1" source="nGLuf51OtG82o4zcJS6--8" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" target="nGLuf51OtG82o4zcJS6--21">- <mxGeometry relative="1" as="geometry" />+ <mxCell id="issue-4" parent="1" style="text;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;html=1;fontSize=11;" value="Occurrences are grouped into Issues by a normalized hash of the stack trace" vertex="1">+ <mxGeometry height="30" width="270" x="30" y="437" as="geometry" /></mxCell>- <mxCell id="nGLuf51OtG82o4zcJS6--8" parent="1" style="swimlane;whiteSpace=wrap;html=1;expand=1;collapsible=0;" value="Issue" vertex="1">- <mxGeometry height="103" width="270" x="12" y="274" as="geometry" />+ <mxCell id="spans-1" parent="1" style="swimlane;whiteSpace=wrap;html=1;expand=1;collapsible=0;" value="Spans" vertex="1">+ <mxGeometry height="110" width="200" x="580" y="330" as="geometry" /></mxCell>- <mxCell id="nGLuf51OtG82o4zcJS6--9" parent="nGLuf51OtG82o4zcJS6--8" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Exception</b><br><i>db failed to open</i>" vertex="1">- <mxGeometry height="60" width="120" x="11" y="31" as="geometry" />+ <mxCell id="spans-2" parent="spans-1" style="text;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;spacingLeft=4;spacingRight=4;overflow=hidden;rotatable=0;whiteSpace=wrap;html=1;fontStyle=2" value="Name: db.load.user<div>Started At: {time}<br>Duration: {time}<br>Parent Span: {span id}</div>" vertex="1">+ <mxGeometry height="70" width="176" x="12" y="30" as="geometry" /></mxCell>- <mxCell id="nGLuf51OtG82o4zcJS6--10" parent="nGLuf51OtG82o4zcJS6--8" style="rounded=0;whiteSpace=wrap;html=1;spacing=2;" value="<b>Message</b><div><br/></div>" vertex="1">- <mxGeometry height="60" width="120" x="139" y="31" as="geometry" />+ <mxCell id="spans-3" parent="1" style="text;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;html=1;fontSize=11;" value="Spans nest under each other via their Parent Span" vertex="1">+ <mxGeometry height="30" width="220" x="570" y="444" as="geometry" />+ </mxCell>+ <mxCell id="attr-1" parent="1" style="swimlane;whiteSpace=wrap;html=1;expand=1;collapsible=0;" value="Attributes" vertex="1">+ <mxGeometry height="79" width="110" x="370" y="560" as="geometry" /></mxCell>- <mxCell id="nGLuf51OtG82o4zcJS6--11" edge="1" parent="1" source="nGLuf51OtG82o4zcJS6--3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;">+ <mxCell id="attr-2" parent="attr-1" style="text;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;spacingLeft=4;spacingRight=4;overflow=hidden;rotatable=0;whiteSpace=wrap;html=1;fontStyle=2" value="Key: UserId&nbsp;<div>Value: 10</div>" vertex="1">+ <mxGeometry height="42" width="90" x="12" y="30" as="geometry" />+ </mxCell>+ <mxCell id="e-issue" edge="1" parent="1" source="trace-1" target="issue-1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;"><mxGeometry relative="1" as="geometry"><Array as="points">- <mxPoint x="145" y="131" />- <mxPoint x="145" y="275" />+ <mxPoint x="165" y="121" />+ <mxPoint x="165" y="280" /></Array>- <mxPoint x="145" y="274" as="targetPoint" /></mxGeometry></mxCell>- <mxCell id="nGLuf51OtG82o4zcJS6--12" connectable="0" parent="nGLuf51OtG82o4zcJS6--11" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="Traces can have Issues&nbsp;<div>attached to them</div>" vertex="1">- <mxGeometry relative="1" x="-0.497" y="3" as="geometry">- <mxPoint x="-35" y="-26" as="offset" />+ <mxCell id="e-issue-label" connectable="0" parent="e-issue" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="Traces can have Issues attached<div>via <i>trace id + trace type</i></div>" vertex="1">+ <mxGeometry relative="1" x="-0.4" y="0" as="geometry">+ <mxPoint x="-60" y="-40" as="offset" /></mxGeometry></mxCell>- <mxCell id="nGLuf51OtG82o4zcJS6--21" parent="1" style="swimlane;whiteSpace=wrap;html=1;expand=1;collapsible=0;" value="Attributes" vertex="1">- <mxGeometry height="79" width="104" x="269" y="437" as="geometry" />+ <mxCell id="e-spans" edge="1" parent="1" source="trace-1" target="spans-1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry">+ <Array as="points">+ <mxPoint x="680" y="121" />+ <mxPoint x="680" y="280" />+ </Array>+ </mxGeometry></mxCell>- <mxCell id="nGLuf51OtG82o4zcJS6--39" parent="nGLuf51OtG82o4zcJS6--21" style="text;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;spacingLeft=4;spacingRight=4;overflow=hidden;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;rotatable=0;whiteSpace=wrap;html=1;fontStyle=2" value="Key: UserId&nbsp;<div>Value: 10</div>" vertex="1">- <mxGeometry height="42" width="106" x="15" y="30" as="geometry" />+ <mxCell id="e-spans-label" connectable="0" parent="e-spans" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="A Trace can have multiple Spans" vertex="1">+ <mxGeometry relative="1" x="-0.4" y="0" as="geometry">+ <mxPoint x="63" y="-40" as="offset" />+ </mxGeometry>+ </mxCell>+ <mxCell id="e-attr" edge="1" parent="1" source="trace-1" target="attr-1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" /></mxCell>- <mxCell id="nGLuf51OtG82o4zcJS6--44" connectable="0" parent="1" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="A Trace can have&nbsp;<div>multiple Attributes</div>" vertex="1">- <mxGeometry x="377" y="305" as="geometry">- <mxPoint x="-8" y="4" as="offset" />+ <mxCell id="e-attr-label" connectable="0" parent="e-attr" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="A Trace can have<div>multiple Attributes</div>" vertex="1">+ <mxGeometry relative="1" x="0.55" y="0" as="geometry">+ <mxPoint x="1" y="0" as="offset" /></mxGeometry></mxCell>- <mxCell id="nGLuf51OtG82o4zcJS6--45" connectable="0" parent="1" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="An Issue can have&nbsp;<div>multiple additional Attributes</div>" vertex="1">- <mxGeometry x="131" y="494" as="geometry">- <mxPoint x="-8" y="4" as="offset" />+ <mxCell id="e-issue-attr" edge="1" parent="1" source="issue-1" target="attr-1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry">+ <Array as="points">+ <mxPoint x="335" y="382" />+ <mxPoint x="335" y="600" />+ </Array></mxGeometry></mxCell>- <mxCell id="nGLuf51OtG82o4zcJS6--46" parent="1" style="swimlane;whiteSpace=wrap;html=1;expand=1;collapsible=0;" value="Spans" vertex="1">- <mxGeometry height="93" width="198" x="460" y="271" as="geometry" />+ <mxCell id="e-issue-attr-label" connectable="0" parent="e-issue-attr" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="An Issue can have<div>multiple additional Attributes</div>" vertex="1">+ <mxGeometry relative="1" x="0.5" y="0" as="geometry">+ <mxPoint x="-78" y="0" as="offset" />+ </mxGeometry></mxCell>- <mxCell id="nGLuf51OtG82o4zcJS6--47" parent="nGLuf51OtG82o4zcJS6--46" style="text;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;spacingLeft=4;spacingRight=4;overflow=hidden;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;rotatable=0;whiteSpace=wrap;html=1;fontStyle=2" value="Name:db.load.user<div>Started At: {time}<br>Duration: {time}</div>" vertex="1">- <mxGeometry height="54" width="174" x="15" y="30" as="geometry" />+ <mxCell id="e-spans-attr" edge="1" parent="1" source="spans-1" target="attr-1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry">+ <Array as="points">+ <mxPoint x="520" y="385" />+ <mxPoint x="520" y="600" />+ </Array>+ </mxGeometry>+ </mxCell>+ <mxCell id="e-spans-attr-label" connectable="0" parent="e-spans-attr" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="Spans can have<div>Attributes as well</div>" vertex="1">+ <mxGeometry relative="1" x="0.5" y="0" as="geometry">+ <mxPoint x="62" y="0" as="offset" />+ </mxGeometry></mxCell></root></mxGraphModel>diff --git a/diagrams/architecture.png b/diagrams/architecture.pngindex 131eecd8..79cc3eaa 100644Binary files a/diagrams/architecture.png and b/diagrams/architecture.png differdiff --git a/diagrams/auth-types.drawio b/diagrams/auth-types.drawionew file mode 100644index 00000000..e069e910--- /dev/null+++ b/diagrams/auth-types.drawio@@ -0,0 +1,158 @@+<mxfile host="app.diagrams.net" version="29.3.6">+ <diagram name="Page-1" id="auth-types-1">+ <mxGraphModel dx="815" dy="558" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1650" pageHeight="720" math="0" shadow="0" adaptiveColors="auto">+ <root>+ <mxCell id="0" />+ <mxCell id="1" parent="0" />+ <mxCell id="sdk" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>App with Traceway SDK<br>or OTel exporter</b>" vertex="1">+ <mxGeometry height="60" width="170" x="40" y="40" as="geometry" />+ </mxCell>+ <mxCell id="ci" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Build / CI</b><br><i>symbol upload</i>" vertex="1">+ <mxGeometry height="60" width="170" x="40" y="150" as="geometry" />+ </mxCell>+ <mxCell id="user" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Dashboard user</b><br><i>browser</i>" vertex="1">+ <mxGeometry height="70" width="170" x="40" y="280" as="geometry" />+ </mxCell>+ <mxCell id="cli" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>traceway CLI</b>" vertex="1">+ <mxGeometry height="60" width="170" x="40" y="470" as="geometry" />+ </mxCell>+ <mxCell id="mcp" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>MCP client</b>" vertex="1">+ <mxGeometry height="60" width="170" x="40" y="600" as="geometry" />+ </mxCell>+ <mxCell id="ptok" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Project token</b><br><i>non-expiring, per project</i>" vertex="1">+ <mxGeometry height="60" width="220" x="280" y="40" as="geometry" />+ </mxCell>+ <mxCell id="smtok" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Source map token</b><br><i>non-expiring, per project</i>" vertex="1">+ <mxGeometry height="60" width="220" x="280" y="150" as="geometry" />+ </mxCell>+ <mxCell id="jwt" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Dashboard JWT</b><br><i>7 days</i>" vertex="1">+ <mxGeometry height="55" width="220" x="280" y="260" as="geometry" />+ </mxCell>+ <mxCell id="pat" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Personal access token twp_</b><br><i>SHA-256 hashed, optional expiry</i>" vertex="1">+ <mxGeometry height="60" width="220" x="280" y="340" as="geometry" />+ </mxCell>+ <mxCell id="devflow" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Device flow (RFC 8628)</b><br><i>user approves the<br>user code at /device</i>" vertex="1">+ <mxGeometry height="80" width="220" x="280" y="460" as="geometry" />+ </mxCell>+ <mxCell id="oauth" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>OAuth code + PKCE</b><br><i>RFC 7591 dynamic registration,<br>consent at /oauth/authorize,<br>single-use twa_ code (5 min)</i>" vertex="1">+ <mxGeometry height="90" width="220" x="280" y="580" as="geometry" />+ </mxCell>+ <mxCell id="tokend" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>POST /api/auth/token</b><br><i>device_code, authorization_code,<br>refresh_token grants</i>" vertex="1">+ <mxGeometry height="70" width="200" x="560" y="520" as="geometry" />+ </mxCell>+ <mxCell id="acc" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Access token</b><br><i>15-min JWT</i>" vertex="1">+ <mxGeometry height="60" width="200" x="820" y="450" as="geometry" />+ </mxCell>+ <mxCell id="ref" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Refresh token twr_</b><br><i>90 days, rotating, family<br>revoked on reuse</i>" vertex="1">+ <mxGeometry height="70" width="200" x="820" y="560" as="geometry" />+ </mxCell>+ <mxCell id="uca" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;" value="<b>UseClientAuth</b>" vertex="1">+ <mxGeometry height="50" width="190" x="1090" y="45" as="geometry" />+ </mxCell>+ <mxCell id="usma" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;" value="<b>UseSourceMapAuth</b>" vertex="1">+ <mxGeometry height="50" width="190" x="1090" y="155" as="geometry" />+ </mxCell>+ <mxCell id="uaa" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;" value="<b>UseAppAuth</b><br><i>JWT or twp_ hash lookup</i>" vertex="1">+ <mxGeometry height="60" width="190" x="1090" y="300" as="geometry" />+ </mxCell>+ <mxCell id="roles" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;" value="<b>Role middleware</b><br><i>RequireProjectAccess<br>RequireWriteAccess (blocks readonly)<br>RequireAdminAccess (owner, admin)</i>" vertex="1">+ <mxGeometry height="90" width="190" x="1090" y="410" as="geometry" />+ </mxCell>+ <mxCell id="ingest" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Telemetry ingestion</b><br><i>/api/report, /api/otel/v1/*,<br>/api/profiles/ingest</i>" vertex="1">+ <mxGeometry height="80" width="240" x="1340" y="30" as="geometry" />+ </mxCell>+ <mxCell id="symup" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Symbol uploads</b><br><i>/api/sourcemaps/upload,<br>/api/symbols/upload</i>" vertex="1">+ <mxGeometry height="70" width="240" x="1340" y="145" as="geometry" />+ </mxCell>+ <mxCell id="app" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Dashboard API + MCP server</b><br><i>scoped by organization role</i>" vertex="1">+ <mxGeometry height="90" width="240" x="1340" y="320" as="geometry" />+ </mxCell>+ <mxCell id="e1" edge="1" parent="1" source="sdk" target="ptok" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e2" edge="1" parent="1" source="ptok" target="uca" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e3" edge="1" parent="1" source="uca" target="ingest" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e4" edge="1" parent="1" source="ci" target="smtok" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e5" edge="1" parent="1" source="smtok" target="usma" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e6" edge="1" parent="1" source="usma" target="symup" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e7" edge="1" parent="1" source="user" target="jwt" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.3;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e7l" connectable="0" parent="e7" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="login / SSO" vertex="1">+ <mxGeometry relative="1" x="0" y="0" as="geometry">+ <mxPoint x="0" y="-10" as="offset" />+ </mxGeometry>+ </mxCell>+ <mxCell id="e8" edge="1" parent="1" source="user" target="pat" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.7;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e8l" connectable="0" parent="e8" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="account page" vertex="1">+ <mxGeometry relative="1" x="0" y="0" as="geometry">+ <mxPoint x="0" y="10" as="offset" />+ </mxGeometry>+ </mxCell>+ <mxCell id="e9" edge="1" parent="1" source="jwt" target="uaa" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.35;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e10" edge="1" parent="1" source="pat" target="uaa" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.65;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e11" edge="1" parent="1" source="cli" target="devflow" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e12" edge="1" parent="1" source="mcp" target="oauth" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e13" edge="1" parent="1" source="devflow" target="tokend" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.25;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e14" edge="1" parent="1" source="oauth" target="tokend" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.75;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e15" edge="1" parent="1" source="tokend" target="acc" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.3;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e16" edge="1" parent="1" source="tokend" target="ref" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.7;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e17" edge="1" parent="1" source="ref" target="tokend" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;dashed=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry">+ <Array as="points">+ <mxPoint x="920" y="660" />+ <mxPoint x="660" y="660" />+ </Array>+ </mxGeometry>+ </mxCell>+ <mxCell id="e17l" connectable="0" parent="e17" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="rotate" vertex="1">+ <mxGeometry relative="1" x="0" y="0" as="geometry">+ <mxPoint x="0" y="-10" as="offset" />+ </mxGeometry>+ </mxCell>+ <mxCell id="e18" edge="1" parent="1" source="acc" target="uaa" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0.25;entryY=1;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry">+ <Array as="points">+ <mxPoint x="920" y="385" />+ <mxPoint x="1137" y="385" />+ </Array>+ </mxGeometry>+ </mxCell>+ <mxCell id="e19" edge="1" parent="1" source="uaa" target="roles" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.6;exitY=1;exitDx=0;exitDy=0;entryX=0.6;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="e20" edge="1" parent="1" source="roles" target="app" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.75;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ </root>+ </mxGraphModel>+ </diagram>+</mxfile>diff --git a/diagrams/auth-types.png b/diagrams/auth-types.pngnew file mode 100644index 00000000..c5115750Binary files /dev/null and b/diagrams/auth-types.png differdiff --git a/diagrams/db-architecture.drawio b/diagrams/db-architecture.drawionew file mode 100644index 00000000..e3b19f47--- /dev/null+++ b/diagrams/db-architecture.drawio@@ -0,0 +1,117 @@+<mxfile host="app.diagrams.net" version="29.3.6">+ <diagram name="Page-1" id="db-architecture-1">+ <mxGraphModel dx="815" dy="558" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1500" pageHeight="1050" math="0" shadow="0" adaptiveColors="auto">+ <root>+ <mxCell id="0" />+ <mxCell id="1" parent="0" />+ <mxCell id="consumers" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Controllers, services, workers</b><br><i>import the facade packages only: transactional.UserRepository, telemetry.SpanRepository, never a backend package directly</i>" vertex="1">+ <mxGeometry height="70" width="1180" x="200" y="40" as="geometry" />+ </mxCell>+ <mxCell id="lmain" parent="1" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=28;" value="Main DB: db.DB (relational / config)" vertex="1">+ <mxGeometry height="330" width="600" x="80" y="170" as="geometry" />+ </mxCell>+ <mxCell id="lfac" parent="lmain" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;" value="<b>repositories/transactional facade</b><br><i>transactional_sqlite.go (default) | transactional_pg.go (-tags transactional_pg)</i>" vertex="1">+ <mxGeometry height="60" width="560" x="20" y="40" as="geometry" />+ </mxCell>+ <mxCell id="lchar" parent="lmain" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;align=left;spacingLeft=8;spacingRight=8;" value="<b>Transactions required:</b> middleware.Transactional / db.ExecuteTransaction (*sql.Tx)<br><i>users, organizations, projects, invitations, widgets, metric_registry, notification config, personal_access_tokens, refresh_tokens, device_authorizations</i><br><i>pg/ and sqlite/ are dialect-neutral twins, parity_test.go enforces byte-for-byte equality</i>" vertex="1">+ <mxGeometry height="105" width="560" x="20" y="115" as="geometry" />+ </mxCell>+ <mxCell id="limp1" parent="lmain" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>sqlite/</b>" vertex="1">+ <mxGeometry height="55" width="170" x="20" y="240" as="geometry" />+ </mxCell>+ <mxCell id="limp2" parent="lmain" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>pg/</b>" vertex="1">+ <mxGeometry height="55" width="170" x="210" y="240" as="geometry" />+ </mxCell>+ <mxCell id="limp3" parent="lmain" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;" value="<b>shared/</b><br><i>token hashing,<br>facade structs</i>" vertex="1">+ <mxGeometry height="55" width="180" x="400" y="240" as="geometry" />+ </mxCell>+ <mxCell id="rtel" parent="1" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=28;" value="Telemetry DB: db.TelemetryDB (append-only telemetry)" vertex="1">+ <mxGeometry height="330" width="680" x="740" y="170" as="geometry" />+ </mxCell>+ <mxCell id="rfac" parent="rtel" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;" value="<b>repositories/telemetry facade</b><br><i>telemetry_sqlite.go (default) | telemetry_duckdb.go (-tags telemetry_duckdb) | telemetry_ch.go (-tags telemetry_ch)</i>" vertex="1">+ <mxGeometry height="60" width="640" x="20" y="40" as="geometry" />+ </mxCell>+ <mxCell id="rchar" parent="rtel" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;align=left;spacingLeft=8;spacingRight=8;" value="<b>No transactions:</b> batch InsertAsync only (ClickHouse PrepareBatch / DuckDB Appender / direct lit inserts)<br><i>endpoints, tasks, ai_traces, spans, exception_stack_traces, metric_points, log_records, sessions, session_recordings, profiles, fired_notifications, archived_exceptions, slow_endpoints</i>" vertex="1">+ <mxGeometry height="105" width="640" x="20" y="115" as="geometry" />+ </mxCell>+ <mxCell id="rimp1" parent="rtel" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>sqlite/</b>" vertex="1">+ <mxGeometry height="55" width="115" x="20" y="240" as="geometry" />+ </mxCell>+ <mxCell id="rimp2" parent="rtel" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>duckdb/</b>" vertex="1">+ <mxGeometry height="55" width="115" x="150" y="240" as="geometry" />+ </mxCell>+ <mxCell id="rimp3" parent="rtel" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>clickhouse/</b>" vertex="1">+ <mxGeometry height="55" width="120" x="280" y="240" as="geometry" />+ </mxCell>+ <mxCell id="rimp4" parent="rtel" style="rounded=0;whiteSpace=wrap;html=1;fontSize=10;" value="<b>sqlitetypes/</b><br><i>scan types for<br>sqlite + duckdb</i>" vertex="1">+ <mxGeometry height="55" width="115" x="415" y="240" as="geometry" />+ </mxCell>+ <mxCell id="rimp5" parent="rtel" style="rounded=0;whiteSpace=wrap;html=1;fontSize=10;" value="<b>shared/</b><br><i>helpers for all<br>backends</i>" vertex="1">+ <mxGeometry height="55" width="115" x="545" y="240" as="geometry" />+ </mxCell>+ <mxCell id="engsm" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>SQLite (main)</b><br><i>SQLITE_PATH, default ./traceway.db<br>no credentials, single file</i>" vertex="1">+ <mxGeometry height="90" width="280" x="80" y="560" as="geometry" />+ </mxCell>+ <mxCell id="engpg" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>PostgreSQL (main)</b><br><i>POSTGRES_HOST / PORT / DATABASE /<br>USERNAME / PASSWORD / SSLMODE</i>" vertex="1">+ <mxGeometry height="90" width="290" x="390" y="560" as="geometry" />+ </mxCell>+ <mxCell id="engst" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>SQLite (telemetry)</b><br><i>traceway_telemetry.db,<br>derived from SQLITE_PATH</i>" vertex="1">+ <mxGeometry height="90" width="215" x="740" y="560" as="geometry" />+ </mxCell>+ <mxCell id="engdd" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;" value="<b>DuckDB (telemetry)</b><br><i>traceway_telemetry.duckdb<br>DUCKDB_MEMORY_LIMIT / THREADS /<br>CHECKPOINT_THRESHOLD<br>CGO required, glibc only</i>" vertex="1">+ <mxGeometry height="100" width="225" x="975" y="560" as="geometry" />+ </mxCell>+ <mxCell id="engch" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>ClickHouse (telemetry)</b><br><i>CLICKHOUSE_SERVER / DATABASE /<br>USERNAME / PASSWORD / TLS</i>" vertex="1">+ <mxGeometry height="90" width="200" x="1220" y="560" as="geometry" />+ </mxCell>+ <mxCell id="combos" parent="1" style="rounded=0;whiteSpace=wrap;html=1;align=left;spacingLeft=10;spacingRight=10;fontSize=11;" value="<b>Supported build combinations (2 build-tag axes: relational store + telemetry store)</b><br><br>1. <b>no tags</b>: SQLite + SQLite (zero-config self-hosted default)<br>2. <b>-tags telemetry_duckdb</b>: SQLite main + DuckDB telemetry (columnar reads, Dockerfile.duckdb, Debian image)<br>3. <b>-tags &quot;transactional_pg telemetry_ch&quot;</b>: PostgreSQL + ClickHouse (cloud / high volume)<br><br><i>Any other combination fails to compile: guard files in backend/app/db/ (guard_pg_without_ch.go, guard_ch_without_pg.go, guard_ch_and_duckdb.go, guard_stale_*.go)</i>" vertex="1">+ <mxGeometry height="190" width="600" x="80" y="710" as="geometry" />+ </mxCell>+ <mxCell id="tree" parent="1" style="rounded=0;whiteSpace=wrap;html=1;align=left;spacingLeft=12;spacingRight=8;fontSize=11;fontFamily=Courier New;" value="<b>Folder structure: backend/app/</b><br><br>db/ &nbsp;.................. connections + build-tag guard files<br>migrations/<br>&nbsp;&nbsp;pg/ (transactional_pg) &nbsp;&nbsp;ch/ (telemetry_ch)<br>&nbsp;&nbsp;sqlite/ + sqlite_telemetry/ (default)<br>&nbsp;&nbsp;duckdb_telemetry/ (telemetry_duckdb)<br>repositories/<br>&nbsp;&nbsp;transactional/ ..... facade: transactional_{sqlite,pg}.go<br>&nbsp;&nbsp;&nbsp;&nbsp;pg/ &nbsp;sqlite/ &nbsp;shared/<br>&nbsp;&nbsp;telemetry/ ......... facade: telemetry_{sqlite,duckdb,ch}.go<br>&nbsp;&nbsp;&nbsp;&nbsp;clickhouse/ &nbsp;duckdb/ &nbsp;sqlite/ &nbsp;shared/ &nbsp;sqlitetypes/" vertex="1">+ <mxGeometry height="230" width="680" x="740" y="710" as="geometry" />+ </mxCell>+ <mxCell id="ec1" edge="1" parent="1" source="consumers" target="lfac" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.25;exitY=1;exitDx=0;exitDy=0;entryX=0.15;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="ec1l" connectable="0" parent="ec1" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="transactions (*sql.Tx)" vertex="1">+ <mxGeometry relative="1" x="0" y="0" as="geometry">+ <mxPoint x="-75" y="0" as="offset" />+ </mxGeometry>+ </mxCell>+ <mxCell id="ec2" edge="1" parent="1" source="consumers" target="rfac" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.75;exitY=1;exitDx=0;exitDy=0;entryX=0.85;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="ec2l" connectable="0" parent="ec2" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="batch InsertAsync + reads" vertex="1">+ <mxGeometry relative="1" x="0" y="0" as="geometry">+ <mxPoint x="85" y="0" as="offset" />+ </mxGeometry>+ </mxCell>+ <mxCell id="ee1" edge="1" parent="1" source="limp1" target="engsm" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="ee2" edge="1" parent="1" source="limp2" target="engpg" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="ee3" edge="1" parent="1" source="rimp1" target="engst" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="ee4" edge="1" parent="1" source="rimp2" target="engdd" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.4;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry">+ <Array as="points">+ <mxPoint x="947" y="520" />+ <mxPoint x="1065" y="520" />+ </Array>+ </mxGeometry>+ </mxCell>+ <mxCell id="ee5" edge="1" parent="1" source="rimp3" target="engch" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry">+ <Array as="points">+ <mxPoint x="1080" y="535" />+ <mxPoint x="1320" y="535" />+ </Array>+ </mxGeometry>+ </mxCell>+ </root>+ </mxGraphModel>+ </diagram>+</mxfile>diff --git a/diagrams/db-architecture.png b/diagrams/db-architecture.pngnew file mode 100644index 00000000..67ecceeeBinary files /dev/null and b/diagrams/db-architecture.png differdiff --git a/diagrams/ingestion-flows.drawio b/diagrams/ingestion-flows.drawionew file mode 100644index 00000000..a5a87e59--- /dev/null+++ b/diagrams/ingestion-flows.drawio@@ -0,0 +1,185 @@+<mxfile host="app.diagrams.net" version="29.3.6">+ <diagram name="Page-1" id="ingestion-flows-1">+ <mxGraphModel dx="815" dy="558" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1650" pageHeight="700" math="0" shadow="0" adaptiveColors="auto">+ <root>+ <mxCell id="0" />+ <mxCell id="1" parent="0" />+ <mxCell id="cA" parent="1" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=26;" value="Traceway SDK clients" vertex="1">+ <mxGeometry height="250" width="240" x="40" y="60" as="geometry" />+ </mxCell>+ <mxCell id="cA1" parent="cA" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>JS SDKs</b><br><i>React, Svelte, Vue, Next.js,<br>React Native</i>" vertex="1">+ <mxGeometry height="60" width="200" x="20" y="38" as="geometry" />+ </mxCell>+ <mxCell id="cA2" parent="cA" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Mobile SDKs</b><br><i>iOS, Android, Flutter</i>" vertex="1">+ <mxGeometry height="60" width="200" x="20" y="110" as="geometry" />+ </mxCell>+ <mxCell id="cA3" parent="cA" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Go SDK</b><br><i>gin, chi, fiber, stdlib</i>" vertex="1">+ <mxGeometry height="55" width="200" x="20" y="182" as="geometry" />+ </mxCell>+ <mxCell id="cB" parent="1" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=26;" value="OpenTelemetry clients" vertex="1">+ <mxGeometry height="180" width="240" x="40" y="360" as="geometry" />+ </mxCell>+ <mxCell id="cB1" parent="cB" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>OTel-instrumented backends</b><br><i>Laravel, Django, NestJS,<br>Hono, Workers, ...</i>" vertex="1">+ <mxGeometry height="70" width="200" x="20" y="38" as="geometry" />+ </mxCell>+ <mxCell id="cB2" parent="cB" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Traceway OTel Agent</b><br><i>host metrics</i>" vertex="1">+ <mxGeometry height="50" width="200" x="20" y="118" as="geometry" />+ </mxCell>+ <mxCell id="report" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>POST /api/report</b><br><i>gzipped JSON<br>collection frames</i>" vertex="1">+ <mxGeometry height="70" width="190" x="340" y="130" as="geometry" />+ </mxCell>+ <mxCell id="otlp" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>POST /api/otel/v1/*</b><br><i>traces, metrics, logs, profiles<br>protobuf or JSON, gzip</i>" vertex="1">+ <mxGeometry height="90" width="190" x="340" y="400" as="geometry" />+ </mxCell>+ <mxCell id="auth" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f5f5f5;" value="<b>Project token auth</b><br><br><i>Authorization:<br>Bearer<br>&lt;project token&gt;</i>" vertex="1">+ <mxGeometry height="400" width="110" x="585" y="110" as="geometry" />+ </mxCell>+ <mxCell id="pA" parent="1" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=26;" value="Report pipeline" vertex="1">+ <mxGeometry height="250" width="300" x="750" y="60" as="geometry" />+ </mxCell>+ <mxCell id="frame" parent="pA" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Parse collection frames</b><br><i>traces, stackTraces, metrics,<br>sessions, recordings</i>" vertex="1">+ <mxGeometry height="60" width="260" x="20" y="35" as="geometry" />+ </mxCell>+ <mxCell id="split" parent="pA" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Traces + nested spans</b><br><i>isTask ? Task : Endpoint</i>" vertex="1">+ <mxGeometry height="55" width="260" x="20" y="110" as="geometry" />+ </mxCell>+ <mxCell id="recq" parent="pA" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Recording uploader</b><br><i>bounded queue + workers</i>" vertex="1">+ <mxGeometry height="55" width="260" x="20" y="180" as="geometry" />+ </mxCell>+ <mxCell id="pB" parent="1" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=26;" value="OTel pipeline" vertex="1">+ <mxGeometry height="250" width="300" x="750" y="360" as="geometry" />+ </mxCell>+ <mxCell id="class" parent="pB" style="rounded=0;whiteSpace=wrap;html=1;align=left;spacingLeft=8;" value="<b>Span classifier</b><br><i>HTTP SERVER span → Endpoint<br>CONSUMER / console.command → Task<br>gen_ai.* attributes → AI Trace<br>other spans → Spans</i>" vertex="1">+ <mxGeometry height="95" width="260" x="20" y="35" as="geometry" />+ </mxCell>+ <mxCell id="evexc" parent="pB" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Exceptions</b><br><i>from span events + exception.* attrs</i>" vertex="1">+ <mxGeometry height="50" width="260" x="20" y="142" as="geometry" />+ </mxCell>+ <mxCell id="conv" parent="pB" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Metric / log / profile converters</b>" vertex="1">+ <mxGeometry height="40" width="260" x="20" y="200" as="geometry" />+ </mxCell>+ <mxCell id="sym" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Symbolication at ingest</b><br><i>JS, Dart, iOS, Android</i>" vertex="1">+ <mxGeometry height="70" width="190" x="1110" y="240" as="geometry" />+ </mxCell>+ <mxCell id="hash" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Normalized stack-trace hash</b><br><i>groups occurrences into Issues</i>" vertex="1">+ <mxGeometry height="70" width="190" x="1110" y="350" as="geometry" />+ </mxCell>+ <mxCell id="store" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Telemetry store</b><br><i>ClickHouse / SQLite / DuckDB</i><br><br><i>endpoints, tasks, ai_traces,<br>spans, exception_stack_traces,<br>metric_points, log_records,<br>sessions, profiles</i>" vertex="1">+ <mxGeometry height="170" width="230" x="1380" y="80" as="geometry" />+ </mxCell>+ <mxCell id="blob" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Object storage</b><br><i>S3 / local disk</i><br><br><i>recording segments,<br>AI conversations</i>" vertex="1">+ <mxGeometry height="110" width="230" x="1380" y="430" as="geometry" />+ </mxCell>+ <mxCell id="eA" edge="1" parent="1" source="cA" target="report" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="eB" edge="1" parent="1" source="cB" target="otlp" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="eR2A" edge="1" parent="1" source="report" target="auth" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.15;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="eO2A" edge="1" parent="1" source="otlp" target="auth" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.85;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="eA2RP" edge="1" parent="1" source="auth" target="pA" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.15;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="eA2OP" edge="1" parent="1" source="auth" target="pB" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.85;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="eF2S" edge="1" parent="pA" source="frame" target="split" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="eC2E" edge="1" parent="pB" source="class" target="evexc" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="eSTACK" edge="1" parent="1" source="frame" target="sym" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.3;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry">+ <Array as="points">+ <mxPoint x="1065" y="125" />+ <mxPoint x="1065" y="261" />+ </Array>+ </mxGeometry>+ </mxCell>+ <mxCell id="eSTACKl" connectable="0" parent="eSTACK" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="stack traces" vertex="1">+ <mxGeometry relative="1" x="-0.85" y="0" as="geometry">+ <mxPoint x="0" y="-10" as="offset" />+ </mxGeometry>+ </mxCell>+ <mxCell id="eEVEXC" edge="1" parent="1" source="evexc" target="sym" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.7;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry">+ <Array as="points">+ <mxPoint x="1090" y="527" />+ <mxPoint x="1090" y="289" />+ </Array>+ </mxGeometry>+ </mxCell>+ <mxCell id="eEVEXCl" connectable="0" parent="eEVEXC" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="raw stacks" vertex="1">+ <mxGeometry relative="1" x="-0.6" y="0" as="geometry">+ <mxPoint x="0" y="-10" as="offset" />+ </mxGeometry>+ </mxCell>+ <mxCell id="eSYM2H" edge="1" parent="1" source="sym" target="hash" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="eH2STORE" edge="1" parent="1" source="hash" target="store" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.15;entryY=1;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry">+ <Array as="points">+ <mxPoint x="1414" y="385" />+ </Array>+ </mxGeometry>+ </mxCell>+ <mxCell id="eH2STOREl" connectable="0" parent="eH2STORE" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="exceptions" vertex="1">+ <mxGeometry relative="1" x="-0.4" y="0" as="geometry">+ <mxPoint x="0" y="-10" as="offset" />+ </mxGeometry>+ </mxCell>+ <mxCell id="eRP2STORE" edge="1" parent="1" source="pA" target="store" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.35;exitDx=0;exitDy=0;entryX=0;entryY=0.35;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="eRP2STOREl" connectable="0" parent="eRP2STORE" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="endpoints, tasks, spans,<div>metrics, sessions</div>" vertex="1">+ <mxGeometry relative="1" x="0.15" y="0" as="geometry">+ <mxPoint x="0" y="-20" as="offset" />+ </mxGeometry>+ </mxCell>+ <mxCell id="eRECQ" edge="1" parent="1" source="recq" target="blob" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.2;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry">+ <Array as="points">+ <mxPoint x="1075" y="267" />+ <mxPoint x="1075" y="332" />+ <mxPoint x="1426" y="332" />+ </Array>+ </mxGeometry>+ </mxCell>+ <mxCell id="eRECQl" connectable="0" parent="eRECQ" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="recording segments" vertex="1">+ <mxGeometry relative="1" x="0.35" y="0" as="geometry">+ <mxPoint x="40" y="12" as="offset" />+ </mxGeometry>+ </mxCell>+ <mxCell id="eO2STORE" edge="1" parent="1" source="pB" target="store" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry">+ <Array as="points">+ <mxPoint x="900" y="640" />+ <mxPoint x="1630" y="640" />+ <mxPoint x="1630" y="165" />+ </Array>+ </mxGeometry>+ </mxCell>+ <mxCell id="eO2STOREl" connectable="0" parent="eO2STORE" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="endpoints, tasks, ai_traces, spans,<div>metrics, logs, profiles</div>" vertex="1">+ <mxGeometry relative="1" x="-0.35" y="0" as="geometry">+ <mxPoint x="0" y="-16" as="offset" />+ </mxGeometry>+ </mxCell>+ <mxCell id="eO2BLOB" edge="1" parent="1" source="pB" target="blob" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.8;exitDx=0;exitDy=0;entryX=0;entryY=0.7;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="eO2BLOBl" connectable="0" parent="eO2BLOB" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="AI conversations" vertex="1">+ <mxGeometry relative="1" x="-0.2" y="0" as="geometry">+ <mxPoint x="0" y="-10" as="offset" />+ </mxGeometry>+ </mxCell>+ </root>+ </mxGraphModel>+ </diagram>+</mxfile>diff --git a/diagrams/ingestion-flows.png b/diagrams/ingestion-flows.pngnew file mode 100644index 00000000..94c41355Binary files /dev/null and b/diagrams/ingestion-flows.png differdiff --git a/diagrams/symbolication-flows.drawio b/diagrams/symbolication-flows.drawionew file mode 100644index 00000000..85e2b663--- /dev/null+++ b/diagrams/symbolication-flows.drawio@@ -0,0 +1,123 @@+<mxfile host="app.diagrams.net" version="29.3.6">+ <diagram name="Page-1" id="symbolication-flows-1">+ <mxGraphModel dx="815" dy="558" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1100" pageHeight="850" math="0" shadow="0" adaptiveColors="auto">+ <root>+ <mxCell id="0" />+ <mxCell id="1" parent="0" />+ <mxCell id="up" parent="1" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=26;" value="Symbol upload from build / CI (source map token)" vertex="1">+ <mxGeometry height="190" width="980" x="40" y="40" as="geometry" />+ </mxCell>+ <mxCell id="jsa" parent="up" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>JS source maps</b><br><i>.js + .map files</i>" vertex="1">+ <mxGeometry height="55" width="220" x="20" y="35" as="geometry" />+ </mxCell>+ <mxCell id="iosa" parent="up" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>iOS dSYM</b><br><i>Mach-O DWARF, per-arch UUIDs</i>" vertex="1">+ <mxGeometry height="55" width="220" x="255" y="35" as="geometry" />+ </mxCell>+ <mxCell id="anda" parent="up" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Android R8</b><br><i>mapping.txt + proguard UUID</i>" vertex="1">+ <mxGeometry height="55" width="220" x="490" y="35" as="geometry" />+ </mxCell>+ <mxCell id="darta" parent="up" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Flutter / Dart</b><br><i>.symbols ELF + arch</i>" vertex="1">+ <mxGeometry height="55" width="220" x="725" y="35" as="geometry" />+ </mxCell>+ <mxCell id="up1" parent="up" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>POST /api/sourcemaps/upload</b>" vertex="1">+ <mxGeometry height="45" width="220" x="20" y="125" as="geometry" />+ </mxCell>+ <mxCell id="up2" parent="up" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>POST /api/symbols/upload</b>" vertex="1">+ <mxGeometry height="45" width="220" x="490" y="125" as="geometry" />+ </mxCell>+ <mxCell id="eu1" edge="1" parent="up" source="jsa" target="up1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="eu2" edge="1" parent="up" source="iosa" target="up2" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.25;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="eu3" edge="1" parent="up" source="anda" target="up2" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="eu4" edge="1" parent="up" source="darta" target="up2" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.75;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="blob" parent="1" style="rounded=0;whiteSpace=wrap;html=1;align=left;spacingLeft=12;" value="<b>Object storage (S3 / local disk)</b><br><i>sourcemaps/&lt;project&gt;/&lt;file&gt; + by-debug-id/&lt;debugId&gt;<br>iossymbols/&lt;project&gt;/&lt;uuid&gt;.dsym<br>androidmappings/&lt;project&gt;/&lt;proguardUuid&gt;.txt<br>dartsymbols/&lt;project&gt;/&lt;buildId&gt;-&lt;arch&gt;.symbols</i>" vertex="1">+ <mxGeometry height="120" width="560" x="250" y="290" as="geometry" />+ </mxCell>+ <mxCell id="tw" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Precompiled .tw lookup blobs</b><br><i>built on first miss, stored<br>next to the artifact</i>" vertex="1">+ <mxGeometry height="90" width="220" x="850" y="305" as="geometry" />+ </mxCell>+ <mxCell id="cache" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>LRU cache</b><br><i>in-memory (default)<br>or mmap disk cache</i>" vertex="1">+ <mxGeometry height="80" width="220" x="850" y="440" as="geometry" />+ </mxCell>+ <mxCell id="eb1" edge="1" parent="1" source="up1" target="blob" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;entryX=0.1;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="eb2" edge="1" parent="1" source="up2" target="blob" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;entryX=0.7;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="ebt" edge="1" parent="1" source="blob" target="tw" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="etc" edge="1" parent="1" source="tw" target="cache" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="ing" parent="1" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=26;" value="Exception ingest (/api/report + OTLP)" vertex="1">+ <mxGeometry height="250" width="1030" x="40" y="560" as="geometry" />+ </mxCell>+ <mxCell id="exc" parent="ing" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Exception arrives</b><br><i>raw stack trace</i>" vertex="1">+ <mxGeometry height="55" width="200" x="20" y="45" as="geometry" />+ </mxCell>+ <mxCell id="pick" parent="ing" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Resolver chosen by<br>project framework</b>" vertex="1">+ <mxGeometry height="55" width="200" x="20" y="150" as="geometry" />+ </mxCell>+ <mxCell id="match" parent="ing" style="swimlane;whiteSpace=wrap;html=1;collapsible=0;startSize=24;fontStyle=2;" value="Frame → artifact matching" vertex="1">+ <mxGeometry height="90" width="760" x="250" y="35" as="geometry" />+ </mxCell>+ <mxCell id="mjs" parent="match" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;" value="<b>JS</b><br>debug id, then<br>file basename" vertex="1">+ <mxGeometry height="52" width="175" x="10" y="30" as="geometry" />+ </mxCell>+ <mxCell id="mios" parent="match" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;" value="<b>iOS</b><br>binary image<br>UUID + offset" vertex="1">+ <mxGeometry height="52" width="175" x="197" y="30" as="geometry" />+ </mxCell>+ <mxCell id="mand" parent="match" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;" value="<b>Android</b><br>proguard UUID<br>from the report" vertex="1">+ <mxGeometry height="52" width="175" x="384" y="30" as="geometry" />+ </mxCell>+ <mxCell id="mdart" parent="match" style="rounded=0;whiteSpace=wrap;html=1;fontSize=11;" value="<b>Dart</b><br>build id + arch<br>from the trace" vertex="1">+ <mxGeometry height="52" width="175" x="571" y="30" as="geometry" />+ </mxCell>+ <mxCell id="resolved" parent="ing" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Symbolicated stack trace</b>" vertex="1">+ <mxGeometry height="55" width="230" x="250" y="150" as="geometry" />+ </mxCell>+ <mxCell id="ehash" parent="ing" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>Normalized hash</b><br><i>computed after symbolication</i>" vertex="1">+ <mxGeometry height="55" width="230" x="520" y="150" as="geometry" />+ </mxCell>+ <mxCell id="ins" parent="ing" style="rounded=0;whiteSpace=wrap;html=1;" value="<b>exception_stack_traces</b><br><i>grouped into Issues</i>" vertex="1">+ <mxGeometry height="55" width="220" x="790" y="150" as="geometry" />+ </mxCell>+ <mxCell id="note" parent="ing" style="text;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;html=1;fontSize=11;fontStyle=2;" value="Symbolication runs at ingest time, before hashing: stored exceptions are never re-symbolicated" vertex="1">+ <mxGeometry height="25" width="620" x="250" y="215" as="geometry" />+ </mxCell>+ <mxCell id="ei1" edge="1" parent="ing" source="exc" target="pick" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="ei2" edge="1" parent="ing" source="pick" target="match" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="ei3" edge="1" parent="ing" source="match" target="resolved" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.15;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="ei4" edge="1" parent="ing" source="resolved" target="ehash" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="ei5" edge="1" parent="ing" source="ehash" target="ins" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="elookup" edge="1" parent="1" source="match" target="cache" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;exitX=0.9;exitY=0;exitDx=0;exitDy=0;entryX=0.55;entryY=1;entryDx=0;entryDy=0;">+ <mxGeometry relative="1" as="geometry" />+ </mxCell>+ <mxCell id="elookupl" connectable="0" parent="elookup" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="artifact lookup" vertex="1">+ <mxGeometry relative="1" x="0" y="0" as="geometry">+ <mxPoint x="55" y="0" as="offset" />+ </mxGeometry>+ </mxCell>+ </root>+ </mxGraphModel>+ </diagram>+</mxfile>diff --git a/diagrams/symbolication-flows.png b/diagrams/symbolication-flows.pngnew file mode 100644index 00000000..ce338a13Binary files /dev/null and b/diagrams/symbolication-flows.png differdiff --git a/docs/pages/learn/build-tags.mdx b/docs/pages/learn/build-tags.mdxindex 0fd6e236..d6452d5d 100644--- a/docs/pages/learn/build-tags.mdx+++ b/docs/pages/learn/build-tags.mdx@@ -2,6 +2,8 @@The Traceway backend uses Go build tags to switch between storage backends and to embed the frontend. Storage is selected on two independent axes: the **telemetry** store (high-volume, append-only data) and the **transactional** store (relational/config data).+<img src="/db-architecture.png" alt="Traceway database architecture: build-tag axes, main vs telemetry stores" style={{ maxWidth: '100%', height: 'auto' }} />+## Tags### Telemetry axisdiff --git a/docs/pages/learn/data-flow.mdx b/docs/pages/learn/data-flow.mdxindex 451bbd63..d1101769 100644--- a/docs/pages/learn/data-flow.mdx+++ b/docs/pages/learn/data-flow.mdx@@ -26,6 +26,12 @@ Here's how the concepts connect in a typical scheduled/async task:3. **Batched and uploaded** β All metrics are batched, compressed, and sent to Traceway with the next collection frame4. **Displayed on dashboard** β Metrics appear in configurable widget groups with line charts, area charts, bar charts, single values, and tables β filterable and groupable by tags+## Ingestion pipelines++On the server side all of this arrives through one of two paths: Traceway SDKs (frontend, mobile, and Go) post gzipped collection frames to `/api/report`, while OpenTelemetry-instrumented backends export OTLP to `/api/otel/v1/*`. Both authenticate with the project token, symbolicate stack traces at ingest, and land in the same telemetry store:++<img src="/ingestion-flows.png" alt="Traceway ingestion pipelines" style={{ maxWidth: '100%', height: 'auto' }} />+## After the data collectionAll this data flows to your Traceway dashboard where you can:diff --git a/docs/pages/learn/index.mdx b/docs/pages/learn/index.mdxindex f0572ef3..1691381d 100644--- a/docs/pages/learn/index.mdx+++ b/docs/pages/learn/index.mdx@@ -37,3 +37,9 @@ Endpoints, Tasks, and AI Traces all carry an `is_root` flag. A row is **non-root<img src="/architecture.png" alt="Traceway Architecture" style={{ maxWidth: '100%', height: 'auto' }} />See [Data Flow](/learn/data-flow) for how these connect during request processing, task execution, and metrics collection.++## Authentication++Every way in has its own credential: SDKs and OTel exporters use the project token, CI uses the source map token for symbol uploads, the dashboard uses a JWT or a personal access token, the [CLI](/learn/cli-auth) uses a device flow, and [MCP clients](/learn/mcp) use OAuth with PKCE. Role middleware scopes what an authenticated user can do.++<img src="/auth-types.png" alt="Traceway authentication types" style={{ maxWidth: '100%', height: 'auto' }} />diff --git a/docs/pages/symbolicator/index.mdx b/docs/pages/symbolicator/index.mdxindex 76afa6ef..18fd3109 100644--- a/docs/pages/symbolicator/index.mdx+++ b/docs/pages/symbolicator/index.mdx@@ -8,6 +8,8 @@ The same engine runs three ways:- **As an [OpenTelemetry Collector processor](/symbolicator/opentelemetry)**, so traces are rewritten before they reach any backend.- **As an importable [Go library](/symbolicator/library)**, so you can call it from your own tooling.+<img src="/symbolication-flows.png" alt="Symbolication flows: upload, matching, caching" style={{ maxWidth: '100%', height: 'auto' }} />+## When and where symbolication runsSymbolication happens **once, at ingest**. A report arrives, each stack trace is resolved frame by frame, and the **resolved** trace is what gets hashed for grouping and stored. Nothing is re-resolved when you view an issue later.diff --git a/docs/public/architecture.png b/docs/public/architecture.pngindex 131eecd8..79cc3eaa 100644Binary files a/docs/public/architecture.png and b/docs/public/architecture.png differdiff --git a/docs/public/auth-types.png b/docs/public/auth-types.pngnew file mode 100644index 00000000..c5115750Binary files /dev/null and b/docs/public/auth-types.png differdiff --git a/docs/public/db-architecture.png b/docs/public/db-architecture.pngnew file mode 100644index 00000000..67ecceeeBinary files /dev/null and b/docs/public/db-architecture.png differdiff --git a/docs/public/ingestion-flows.png b/docs/public/ingestion-flows.pngnew file mode 100644index 00000000..94c41355Binary files /dev/null and b/docs/public/ingestion-flows.png differdiff --git a/docs/public/symbolication-flows.png b/docs/public/symbolication-flows.pngnew file mode 100644index 00000000..ce338a13Binary files /dev/null and b/docs/public/symbolication-flows.png differ