Skip to content

Commit 8b79b83

Browse files
arhumanarhuman
committed
docs(readme): lead with getting started, tighten diagnosis and efficiency claims
1 parent cfc166e commit 8b79b83

1 file changed

Lines changed: 58 additions & 63 deletions

File tree

‎README.md‎

Lines changed: 58 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,15 @@
55
Open source. Start free on the [hosted service](https://www.mapi-ng.com) (no card), or self-host the complete MIT stack.
66

77
mAPI-ng answers one question: my endpoint got slower or started failing, what is the most
8-
likely cause, and what should I check next? It correlates RED with Go runtime, per-instance,
9-
deployment, and downstream signals as a pure function over data the page already loads, then
10-
ranks the likely causes and shows the evidence behind each. Every cause carries a
8+
likely cause, and what should I check next? It correlates RED metrics with Go runtime,
9+
instance, deployment, and downstream signals, then ranks the most plausible causes and shows
10+
the evidence behind each. Every cause carries a
1111
"Rules this out:" line so you can falsify it, and when nothing explains the anomaly it says
1212
"Unattributed" rather than inventing a cause.
1313

1414
Instrument in a few lines: two imports, construct a recorder, add one middleware, set one env
15-
var. An absent key makes the middleware a no-op, so adding mAPI-ng is always safe and
16-
activation is decoupled from the code change.
15+
var. An absent key keeps the middleware inactive and prevents data transmission, so
16+
instrumentation can be merged independently from activation.
1717

1818
![Endpoint-detail diagnosis card: "Memory / GC pressure, High (3/4 signals)" ranking a
1919
worsening memory leak from correlated evidence (post-GC heap climbing 3.4x, allocation rate
@@ -37,8 +37,8 @@ Grafana, or YAML to operate.
3737

3838
**Efficiency.** The client aggregates per-endpoint metrics in-process into a
3939
DDSketch before sending. The server stores compact Summaries in ClickHouse and rolls them up
40-
through 1-minute, 1-hour, and 1-day tiers. More data per second ingested, less disk used,
41-
faster queries than raw-event pipelines.
40+
through 1-minute, 1-hour, and 1-day tiers. In-process aggregation reduces transmitted, stored,
41+
and queried data compared with raw-event collection.
4242

4343
---
4444

@@ -53,48 +53,6 @@ For the full product framing, design decisions, and terminology, see [`docs/cont
5353

5454
---
5555

56-
## Repo layout
57-
58-
```
59-
mAPI-ng/
60-
client/ Go module: github.com/arhuman/maping/client (MIT)
61-
gin/ Go module: github.com/arhuman/maping/client/gin (MIT, Gin adapter)
62-
server/ Go module: github.com/arhuman/maping/server (MIT)
63-
cmd/maping-server/
64-
internal/
65-
proto/ Go module: github.com/arhuman/maping/proto (MIT, shared protobuf)
66-
example/ Go module: github.com/arhuman/maping/example (MIT, runnable quickstart)
67-
Dockerfile maping-server image (Go workspace build)
68-
docker-compose*.yml neutral base + local/prod overlays
69-
env.sample template for .env (make local / make up read it)
70-
LICENSE MIT license (applies to the whole repository)
71-
docs/context.md Product framing, design decisions, terminology
72-
docs/adr/ Architecture Decision Records
73-
go.work Workspace tying proto, client, client/gin, server, and example together
74-
```
75-
76-
The repository is an **open-source, multi-module** project: every module (`proto`, `client`,
77-
the framework adapters, and `server`) is **MIT** (auditable, safe to import into production hot
78-
paths, free to self-host and modify). Keeping the Gin adapter in a separate module means importing
79-
the core client never pulls Gin into your binary.
80-
81-
The modules are wired together for local development by `go.work`, so build and test from the
82-
repo root (or anywhere inside the tree). The workspace resolves cross-module imports from
83-
source. Published tags are cut with `make release VERSION=vX.Y.Z`, which pins each module to
84-
the real released versions of its siblings (no local `replace` directives leak to consumers).
85-
86-
---
87-
88-
## Documentation
89-
90-
User-facing documentation (quickstart, what data is collected, runtime overhead, failure
91-
and retry behaviour, security and data flow, self-hosting, architecture, benchmarks, and
92-
licensing) lives in [`server/docs/content/`](server/docs/content/) and is served by the
93-
running server at **`/doc`** (public, no configuration, community build included). Deeper
94-
design rationale lives in the [Architecture Decision Records](docs/adr/).
95-
96-
---
97-
9856
## Getting started
9957

10058
**Run the collector and dashboard (one command):**
@@ -142,16 +100,6 @@ export MAPING_KEY=your-ingest-key # the only required input; absent = no-op
142100

143101
**Full details:** [`client/README.md`](client/README.md), [`server/README.md`](server/README.md), [`proto/README.md`](proto/README.md)
144102

145-
---
146-
147-
## Architecture Decision Records
148-
149-
Design decisions are recorded one file per decision under [`docs/adr/`](docs/adr/); see the
150-
[ADR index](docs/adr/README.md) for the full list, including the diagnosis engine
151-
([0021](docs/adr/0021-diagnosis-engine.md)) and the MIT relicense
152-
([0022](docs/adr/0022-relicense-server-mit.md)).
153-
154-
155103
---
156104

157105
## Hosted or self-hosted
@@ -167,6 +115,57 @@ at any time. Convenience, not lock-in.
167115

168116
---
169117

118+
## Repo layout
119+
120+
```
121+
mAPI-ng/
122+
client/ Go module: github.com/arhuman/maping/client (MIT)
123+
gin/ Go module: github.com/arhuman/maping/client/gin (MIT, Gin adapter)
124+
server/ Go module: github.com/arhuman/maping/server (MIT)
125+
cmd/maping-server/
126+
internal/
127+
proto/ Go module: github.com/arhuman/maping/proto (MIT, shared protobuf)
128+
example/ Go module: github.com/arhuman/maping/example (MIT, runnable quickstart)
129+
Dockerfile maping-server image (Go workspace build)
130+
docker-compose*.yml neutral base + local/prod overlays
131+
env.sample template for .env (make local / make up read it)
132+
LICENSE MIT license (applies to the whole repository)
133+
docs/context.md Product framing, design decisions, terminology
134+
docs/adr/ Architecture Decision Records
135+
go.work Workspace tying proto, client, client/gin, server, and example together
136+
```
137+
138+
The repository is an **open-source, multi-module** project: every module (`proto`, `client`,
139+
the framework adapters, and `server`) is **MIT** (auditable, safe to import into production hot
140+
paths, free to self-host and modify). Keeping the Gin adapter in a separate module means importing
141+
the core client never pulls Gin into your binary.
142+
143+
The modules are wired together for local development by `go.work`, so build and test from the
144+
repo root (or anywhere inside the tree). The workspace resolves cross-module imports from
145+
source. Published tags are cut with `make release VERSION=vX.Y.Z`, which pins each module to
146+
the real released versions of its siblings (no local `replace` directives leak to consumers).
147+
148+
---
149+
150+
## Documentation
151+
152+
User-facing documentation (quickstart, what data is collected, runtime overhead, failure
153+
and retry behaviour, security and data flow, self-hosting, architecture, benchmarks, and
154+
licensing) lives in [`server/docs/content/`](server/docs/content/) and is served by the
155+
running server at **`/doc`** (public, no configuration, community build included). Deeper
156+
design rationale lives in the [Architecture Decision Records](docs/adr/).
157+
158+
---
159+
160+
## Architecture Decision Records
161+
162+
Design decisions are recorded one file per decision under [`docs/adr/`](docs/adr/); see the
163+
[ADR index](docs/adr/README.md) for the full list, including the diagnosis engine
164+
([0021](docs/adr/0021-diagnosis-engine.md)) and the MIT relicense
165+
([0022](docs/adr/0022-relicense-server-mit.md)).
166+
167+
---
168+
170169
## License
171170

172171
mAPI-ng is released under the **MIT License**: the whole repository, every module
@@ -180,10 +179,6 @@ for why the server moved from BSL 1.1 to MIT.
180179

181180
## Development
182181

183-
This repository is a [Go workspace](https://go.dev/doc/tutorial/workspaces), which means you can work on all modules (`proto`, `client`, `server`, etc.) simultaneously. The `go.work` file at the root handles the build.
184-
185-
To get started, you only need to run `make local` to stand up the full development stack (server, ClickHouse, Postgres).
186-
187182
Key `Makefile` targets for contributors:
188183
- `make test`: Run all tests.
189184
- `make audit`: Run linting and vulnerability checks.

0 commit comments

Comments
 (0)