supabase / supabase-flutter / 36168016912
94%

DEFAULT BRANCH: main
Ran
Jobs 11
Files 171
Run time 1min
Badge
Embed ▾
README BADGES
x

If you need to use a raster PNG badge, change the '.svg' to '.png' in the link

Markdown

Textile

RDoc

HTML

Rst
coverage: 91.135%. Remained the same
36168016912

push

github

web-flow 
docs(supabase_flutter): document request ids and trace propagation (#1887)

## Summary

Trace propagation and request ids had no documentation outside their
dartdocs. This adds a "Request ids and tracing" section to the
`supabase_flutter` README, plus a short pointer to it from the
`supabase` README. It covers the current API: the options shape from
#1882 and `requestId` from #1885.

The section starts with the request id, because most people need it and
it needs no setup, and covers tracing after it:

- **Request id on a failure**: `requestId` on `SupabaseException`, what
to do with it (log explorer, support), that `toString()` includes it,
the `sb-request-id`/`x-request-id` fallback, and when it is `null`.
- **Trace propagation**: opt-in through `TracePropagationOptions`, with
recipes for Sentry (`formatAsW3CHeader(span.toSentryTrace())` plus
baggage), OpenTelemetry (the global propagator into a map, then
`TraceContext.fromCarrier`), and `TraceContext.w3c` for other tracing
tools.
- Which hosts receive the headers (third-party hosts never do), that
realtime broadcasts over HTTP carry them but the WebSocket does not, and
how sampling works with `respectSamplingDecision`.

## Testing

The Sentry, OpenTelemetry, `TraceContext.w3c` and `requestId` snippets
were compiled in a scratch project against this branch's packages,
`sentry` 9.22.0 and `opentelemetry` 0.18.11, and `dart analyze` reports
no issues.

## Not in this PR

The ticket also asks for an entry in the Dart reference spec in
supabase/supabase. That repository only has `supabase_dart_v1.yml` and
`supabase_dart_v2.yml`, and both features only exist in 3.0.0, so the
entry has to go into a v3 spec once one exists.

Part of SDK-1939.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Added guidance on using request IDs from client exceptions to locate
corresponding server logs across authentication, database, storage, and
fu... (continued)

8697 of 9543 relevant lines covered (91.13%)

4.92 hits per line

Jobs
ID Job ID Ran Files Coverage
3 supabase - 36168016912.3 18
93.71
GitHub Action Run
4 supabase_functions - 36168016912.4 4
96.0
GitHub Action Run
5 supabase_storage - 36168016912.5 9
97.83
GitHub Action Run
6 supabase_auth - 36168016912.6 32
92.06
GitHub Action Run
7 iceberg - 36168016912.7 6
68.52
GitHub Action Run
8 postgrest - 36168016912.8 28
94.11
GitHub Action Run
9 supabase_typegen - 36168016912.9 24
95.2
GitHub Action Run
10 supabase_realtime - 36168016912.10 13
90.66
GitHub Action Run
11 supabase_flutter - 36168016912.11 14
78.5
GitHub Action Run
8 supabase_common - 35998092270.8 22
87.5
GitHub Action Run
2 yet_another_json_isolate - 35608843571.2 1
98.44
GitHub Action Run
Source Files on build 36168016912