@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
mdx 117 lines 6.13 KB
Raw
1 ---
2 title: Observability
3 description: Trace how commands, events and reactions flow through an @alchemy.run/domain model, across Durable Objects and over hours. Automatic spans, correlation ids and metrics, plus the attributes you choose to record.
4 ---
5
6 A model records what it does as it does it. Every command, every event it commits, and every policy, view, projection and saga that reacts to it gets a span, named after the building block. The spans connect into traces that follow a flow from a click to everything it caused.
7
8 [Part 7 of the tutorial](/domain/tutorial/part-7) sets this up step by step for the bank.
9
10 ## Export the traces
11
12 A hosted model records into whatever tracer the runtime provides. Send it to an OpenTelemetry backend, such as Axiom, Honeycomb or your own collector, to see each flow as one connected trace. The bank declares its Axiom datasets and an ingest token next to its Worker:
13
14 ```typescript title="packages/server/src/Observability.ts"
15 return Axiom.Telemetry({ token: ingest, traces, logs, serviceName: "bank" });
16 ```
17
18 and provides that Layer to the Worker, with the rest of what it hosts. `Alchemy.Telemetry.layerOtlp` does the same for any OTLP endpoint.
19
20 `Cloudflare.Telemetry()` shows a Worker's spans in Cloudflare's dashboard instead, with no backend to run. Cloudflare starts a new trace for every Worker and Durable Object event, so a flow that crosses objects shows up as separate traces, joined only by `domain.correlation_id`, and spans from a browser can't be added.
21
22 ## Follow a command
23
24 A withdrawal sent from the app shows up as one trace, crossing the Worker and two Durable Objects:
25
26 ```text
27 Domain.send Account.WithdrawMoney the Worker, where the Api received it
28 └─ Domain.decide Account.WithdrawMoney the account's Durable Object: decide and commit
29 │ event MoneyWithdrawn one span event per committed event
30 ├─ Domain.view AccountSummary
31 ├─ Domain.view DailyOutflow
32 └─ Domain.policy FraudReview
33 ├─ Domain.external FraudCheck.score
34 └─ Domain.send Account.FreezeAccount
35 └─ Domain.decide Account.FreezeAccount
36 ```
37
38 Each event carries the span that committed it, so the policies and views that react to it continue the same trace, however long the delivery took.
39
40 ## Trace the browser
41
42 foldkit traces every Command it runs, and every Api call carries the caller's trace on, so the browser can start the trace: a click, the commands it sends, and everything they cause on the server. Give the app a tracer that exports to its own origin:
43
44 ```typescript title="packages/web/src/entry.ts"
45 const Tracing = OtlpTracer.layer({
46 url: `${location.origin}/api/telemetry/v1/traces`,
47 resource: { serviceName: "bank-web" },
48 }).pipe(Layer.provide(OtlpSerialization.layerJson));
49 ```
50
51 ## Collect it through your Worker
52
53 `Telemetry.relay` receives the browser's spans in your own Worker and forwards them to wherever the Worker's telemetry goes, with the Worker's credentials. No ingest token reaches a browser, and only signed-in users may send. `signedIn` is the Worker's check of the request's session (see [Sessions and middleware](/domain/sessions#sign-the-session)):
54
55 ```typescript title="packages/server/src/BankWorker.ts"
56 const telemetry = Telemetry.relay({
57 authorize: HttpServerRequest.pipe(Effect.flatMap(signedIn), Effect.map(Option.isSome)),
58 });
59 ```
60
61 Mount it under the Api's path, so the app's Worker forwards it like any other call:
62
63 ```typescript title="packages/server/src/BankWorker.ts"
64 if (path.startsWith("/api/telemetry/")) return yield* telemetry;
65 ```
66
67 `route` decides where each batch goes: the Worker's own destinations, a separate dataset for browser traces, or anywhere else. Cloudflare Workers Observability only records a Worker's own spans, so send browser spans to an OTLP destination such as Axiom.
68
69 ## See every outcome
70
71 A decide span records how the command ended in `domain.outcome`: `accepted`, or the tag of its rejection. A rejection is an answer, not a failure, so its span ends cleanly; only a defect marks a span as failed.
72
73 ## Follow a flow across traces
74
75 Some work starts later, or has many causes. A saga can run for days, a projection batch handles events from many commits, and a scheduled command fires long after it was scheduled. Each starts its own trace and links to the span that caused it.
76
77 Every span carries `domain.correlation_id`, the id of the first command in the flow. One query on it finds a whole business flow, across every trace it took.
78
79 ## Record what matters to you
80
81 Nothing from a command or event is recorded unless you ask for it. Return the attributes you want from `attributes`, on the declaration:
82
83 ```typescript title="packages/domain/src/Account/WithdrawMoney.command.ts"
84 attributes: (cmd) => ({ "bank.amount": cmd.amount }),
85 ```
86
87 Commands, events and rejections all accept it. Events and rejections take it as a third argument: `Domain.Event("MoneyWithdrawn", { amount: Cents }, { attributes: (e) => ({ ... }) })`.
88
89 ## Keep secrets out
90
91 A `Redacted` value is recorded as `<redacted>`, even when you return it from `attributes`. Make a secret field `Schema.Redacted(...)` and it never reaches a trace, or a log.
92
93 ## Annotate from a handler
94
95 An effectful `decide`, a policy, a saga step and a projection all run inside their span, so plain Effect annotates it:
96
97 ```typescript
98 WithdrawMoney: Effect.fn(function* (s, cmd) {
99 yield* Effect.annotateCurrentSpan("bank.tier", s.tier);
100 yield* Effect.log("large withdrawal");
101 // ...
102 }),
103 ```
104
105 Logs from a handler carry the span's trace and its `domain.*` attributes, so they line up with the trace that caused them.
106
107 ## Watch it keep up
108
109 The model counts and times its work as metrics: `domain.commands` and `domain.command.duration` by command and outcome, `domain.events` by event, `domain.lag` from commit to handling for each policy and projection, `domain.runs` by outcome, `domain.projection.batch_size`, and `domain.external.calls`. Lag is the number that tells you whether reactions keep up with commits.
110
111 ## Trace less
112
113 Views apply every event they fold, so they're the busiest spans. Turn them off on the Layer that hosts the model:
114
115 ```typescript
116 Bank.layer(BankHandlers, { telemetry: { views: false } })
117 ```