Skip to content

feat(ui): a screen for connecting telemetry (#232) - #239

Merged
vishr merged 3 commits into
mainfrom
feat/connect-telemetry
Sep 7, 2026
Merged

vishr merged 3 commits into
mainfrom
feat/connect-telemetry

Conversation

@vishr

@vishr vishr commented Sep 7, 2026 •

Copy link
Copy Markdown
Member

What changed

A screen for connecting telemetry, reachable from the account menu. Closes P1 item 6 from #232.

Signed in as an administrator on the demo, nothing in the product said where to send telemetry or how to authenticate. The endpoint and token are shown once during first-run setup and are unreachable afterwards, so anyone who liked what they saw could not take the next step and point their own collector at it.

The capability was already there — GET /api/settings/ingest and the admin-gated POST /api/settings/ingest/rotate-token have existed all along, the latter writing an ingest_key.rotated audit event. What was missing was any way to reach them.

The page

  • Endpoint and Authorization as copyable facts. The Authorization line reads Bearer <your token> rather than implying a token can be revealed: only the hash is stored, and the hint says so.
  • A collector block with this instance's own endpoint substituted and the token left as ${FANOUT_INGEST_TOKEN}, because a secret pasted into a config file is a secret in version control. tls.insecure appears only when the instance serves plaintext.
  • Token state, then rotation behind a confirmation that names the consequence: any collector still sending with the old token is rejected until it is updated. The new token is revealed once, in the header form you paste.

Roles. Every role can read ingest metadata, so a viewer gets the endpoint and the configuration and is told an administrator handles rotation. Only an admin sees the control.

Empty state. An instance with no token says it is rejecting telemetry and offers to issue one, rather than showing a card with nothing in it.

Two other changes to the shell

The account menu carried outbound links to GitHub and the vendor site and no way to reach the workspace's own settings — the one thing an operator came there for was the one thing missing. It is account actions only now: identity, Connect telemetry, Sign out.

Documentation had no link anywhere in the product, and fanout.run appears nowhere in this repository. Following how developer products place it — Anthropic's console keeps Docs in the top chrome beside the avatar, Rise puts a contextual "Learn more" beside the credential — there is now a book icon in the header, reachable from any page, and one contextual line at the foot of this page pointing at the ingest documentation. Both URLs live in ui/links.ts.

Needs your confirmation: https://fanout.run/docs and /docs/ingest are placeholders — nothing in the repo names the real paths. Also, no link to the source repository survives in the application; for an Apache-2.0 product that may be wrong, and it is one line to restore.

Verification

  • just check
  • just test-race when auth, API, ingest, query, MCP, or agent paths changed — no Go paths changed
  • User-facing behavior and configuration docs are current
  • No credentials, private telemetry, host details, or enterprise-only source are included
  • API, migration, ingest, MCP/AG-UI, or release-contract changes are called out — no API change; this is a client for endpoints that already existed

Five tests cover the states: the collector block carrying the instance's endpoint and an env-var token, the confirmation appearing without rotating anything, the one-time reveal after rotation, a viewer seeing no rotate control, and the no-token instance saying it is rejecting telemetry. Rotation was also exercised against a local instance, which is how a bug was caught before review: the reveal read token from the response where the API returns ingest_token, so it silently never appeared.

@vishr

vishr commented Sep 7, 2026 •

Copy link
Copy Markdown
Member Author

Review fixes pushed as 61141a52.

  • Rotation now refreshes the settings it just changed. The response's refreshed settings are written back to the query cache without the plaintext, so issuing a token no longer leaves the page saying the workspace is rejecting telemetry and offering a filled "Issue token" button that would destroy the token just handed over.
  • Both docs links were 404s. The docs site is in this repo under site/, and Starlight serves that collection from the site root — there is no /docs prefix. The header now points at https://fanout.run/ and the ingest link at https://fanout.run/start/send-telemetry, the page that carries the same collector snippet this screen generates. Verified both return 200, and that /docs and /docs/ingest return 404.
  • The generated YAML could be invalid and disagreed with the docs. The endpoint is quoted (an advertised IPv6 endpoint is a flow sequence bare), the token is ${env:FANOUT_INGEST_TOKEN} as the docs use, and the header keeps its capitalization.
  • The TLS hint was backwards. tls_configured means Fanout holds the certificate itself. tls.insecure is emitted only when neither that nor an https:// advertised endpoint is true, and the hint no longer asserts plaintext when a proxy may be terminating TLS.
  • Failure states. A failed load is an alert with a retry rather than a spinner beside the word "unavailable". A failed rotation is cleared by Cancel and by Done; Done also drops the plaintext from the mutation cache. A rotation whose response never arrives says the token may have been issued anyway.

Four new tests cover the first, second (https case), and last two. Verified against a local instance: rotated through the UI, and the issued token was accepted at the OTLP endpoint while the previous one was rejected 401.

just check green.

@vishr

vishr commented Sep 7, 2026 •

Copy link
Copy Markdown
Member Author

Second round of review fixes pushed as 78096ecd.

  • One name for the token. The generated block used FANOUT_INGEST_TOKEN while site/src/content/docs/start/send-telemetry.mdx and the README both say INGEST_TOKEN — follow the docs, then paste this block, and the collector sends an empty bearer and gets a 401. The screen now uses INGEST_TOKEN.
  • The docs snippet has the opposite problem and it is fixed there: the otlp exporter uses TLS by default and the published block never says so, so it fails against any instance that is not behind a TLS terminator. The page now says it, and points at this screen for a block with the reader's own endpoint already in it.
  • Port 443 counts as TLS. An operator naming a terminating proxy usually writes the port, not the scheme, and the page was handing them tls.insecure against a TLS port.
  • The plaintext really leaves the tab. reset() drops the observer but leaves the mutation's result in the cache for another five minutes, reachable from devtools in one step. gcTime: 0 takes it with the reset. The test asserts the mutation cache no longer contains the token, and I verified it fails without that option.
  • Rotation cancels an in-flight settings load before it writes, so a GET already on its way cannot write the pre-rotation answer over the refreshed one.
  • The docs link went to the marketing landing page rather than where an operator starts reading; it now points at /start/what-fanout-is.
  • A failed background refetch no longer replaces an already-loaded page with a full-screen alert — the gate is on data, not isError.

One thing I could not do: I wrote a test for the in-flight-GET race and it passed with and without cancelQueries, so it did not discriminate and I removed it rather than leave a test that proves nothing. The guard stays — it is correct and cheap — but the evidence for it is the analysis, not a red test.

just check green; 102 UI tests pass.

Signed in as an administrator, nothing in the product said where to send
telemetry or how to authenticate. The endpoint and token were shown once during
first-run setup and were unreachable afterwards, so anyone who liked what they
saw could not take the next step and point their own collector at it.

The capability was already there — GET /api/settings/ingest and the admin-gated
rotate endpoint have existed all along, with an audit event. What was missing
was any way to reach them.

Connect telemetry states the endpoint and the header, then gives the collector
block with this instance's own endpoint already in it and the token left as
${FANOUT_INGEST_TOKEN}, because a secret pasted into a config file is a secret
in version control. The token section says what is true — only the hash is
stored, so an existing token cannot be shown — and offers rotation behind a
confirmation that names the consequence: any collector still sending with the
old token is rejected until it is updated. The new token is revealed once.

A viewer sees the connection details and the configuration, since every role
can read ingest metadata; only an administrator sees the rotate control. An
instance with no token yet says it is rejecting telemetry and offers to issue
one, rather than showing an empty card.

Reported in #232 (P1 item 6).

Claude-Session: https://claude.ai/code/session_017ovmTezqzvxVP8P9MGDQNk
Review findings on the connect-telemetry screen, all of them cases where the
page stated something that was not so.

Rotating did not refresh the settings it had just changed. On a workspace with
no token, issuing one left the paragraph above still reading "this workspace
has no token yet, so it is rejecting telemetry", and Done returned the admin to
a filled "Issue token" button — one press away from destroying the token they
had just pasted into a collector. The response already carries the refreshed
settings; they are written back to the cache, without the plaintext, which
belongs in no cache.

Both documentation links were 404s. The docs site is in this repository under
site/, and Starlight serves that collection from the site root, so there is no
/docs prefix: the header goes to fanout.run and the ingest link to
fanout.run/start/send-telemetry, the page that carries the same collector
snippet this screen generates.

The collector block could be invalid YAML and disagreed with the documentation.
An advertised IPv6 endpoint arrives as "[2001:db8::1]:4317", which unquoted is a
flow sequence, so the endpoint is quoted. The token is referenced as
${env:FANOUT_INGEST_TOKEN}, the form the docs use and the only one that is
unambiguous when a distribution sets its own default config scheme, and the
header keeps the capitalization the field above shows.

The TLS hint was backwards. tls_configured means Fanout holds the certificate
itself, not that TLS is terminated at the edge; an advertised https endpoint
also means TLS. The exporter now gets tls.insecure only when neither is true,
and the hint says a proxy in front of Fanout may still be terminating TLS
rather than asserting plaintext.

A failed load showed a spinner beside the words "unavailable", which reads as
still working. It is an alert with a retry now. A rotation that fails leaves
its error standing over the dialog until it is reopened; Cancel and Done clear
it, and Done also drops the plaintext from the mutation cache, which otherwise
held it for the life of the tab. A rotation whose response never arrives says
so, and says the token may have been issued anyway, instead of showing the
browser's "Failed to fetch".

Four new tests: issuing stops the page offering to issue again, an https
endpoint omits tls.insecure, a failed rotation is explained and forgotten on
reopen, and a failed load offers a retry.

Claude-Session: https://claude.ai/code/session_017ovmTezqzvxVP8P9MGDQNk
Second round of review findings on the connect-telemetry screen.

The environment variable in the generated block was FANOUT_INGEST_TOKEN while
the documentation and the README both say INGEST_TOKEN. Following the docs and
then pasting this block gave the collector an empty bearer and a 401. One name
now: INGEST_TOKEN.

The documentation's own collector block has the opposite problem — the otlp
exporter uses TLS by default and the snippet never says so, which fails against
any instance that is not behind a TLS terminator. It says so now, and points at
this screen for a block with the reader's own endpoint in it.

An endpoint on port 443 is treated as TLS. An operator pointing at a
terminating proxy usually writes the port and not the scheme, and the page was
handing them tls.insecure against a TLS port — a gRPC error that explains
nothing.

The plaintext token really does leave the tab now. Resetting the mutation
dropped its observer but left the result in the mutation cache for another
five minutes, reachable from the devtools in one step; gcTime zero takes it
with the reset. A test asserts the cache no longer contains it, and fails
without that option.

A rotation cancels an in-flight settings load before it writes. A GET that was
already on its way resolves after the POST and can write the pre-rotation
answer over the refreshed one — the failure this page was just fixed for.

The documentation link went to the marketing page rather than where an
operator starts reading. A failed background refetch no longer replaces a
page that has already loaded with a full-screen alert.

Claude-Session: https://claude.ai/code/session_017ovmTezqzvxVP8P9MGDQNk
@vishr
vishr force-pushed the feat/connect-telemetry branch from 78096ec to 164022d Compare September 7, 2026 15:32
@vishr
vishr merged commit f0f011c into main Sep 7, 2026
8 checks passed
@vishr
vishr deleted the feat/connect-telemetry branch September 7, 2026 15:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant