> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/docs/adr/0003-umami-optional-analytics.md).

# 0003. Umami Optional Analytics Provider

**Status:** Accepted **Date:** 2026-05-28

## Context

The PRD requires hosted analytics guardrails while keeping the product local-first. A May 2026 service-discovery pass recorded PostHog as historical context, but the project selected Umami for lightweight, open-source-compatible analytics work.

## Options Considered

1. Use Umami as the default optional analytics provider.
2. Use PostHog as the default provider.
3. Omit analytics entirely.

## Decision

Use Umami as the default optional analytics provider. Keep it behind a FactionOS-owned integration boundary that is explicitly controlled, replaceable, and self-hostable.

## Consequences

* Analytics is not a current core dependency.
* Runtime analytics requires explicit public config, consent, opt-out handling, payload scrubbing, host/version filtering, and tests.
* Browser sends use Umami `/api/send` only for approved minimized events; no Umami API key is exposed to the browser.
* Replay, recorder, heatmap, console-log capture, site apps, and replay-style inspection must stay off unless a later reviewed spec explicitly enables them.
* Prompts, transcripts, file contents, terminal output, secret values, full local paths, and PII must not be sent.

## Implementation Status

As of 2026-06-07, the web app includes an optional runtime sender behind the guardrails above. Local self-hosted Umami setup and browser verification are documented in `../runbooks/local-umami-analytics.md`. This does not make Umami a core dependency and does not create a production-hosted analytics claim.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/docs/adr/0003-umami-optional-analytics.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.