@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 370 lines 13.7 KB
Raw
1 ---
2 title: "Part 7: Observe it"
3 description: Send the bank's traces and logs to Axiom, follow a deposit through every Durable Object it reaches, and trace clicks from the browser.
4 sidebar:
5 order: 7
6 ---
7
8 The bank already records a span for every command, event, view and policy. Nothing receives them yet. In this part you send them to [Axiom](/axiom), then add the browser's spans, so one trace runs from a click to every Durable Object it reaches.
9
10 ```text
11 the bank's Worker and Durable Objects ──────────────────────────▶ Axiom
12 the browser app ──────────────────▶ the bank's Worker (relay) ──▶ Axiom
13 ```
14
15 You need a [configured Axiom profile](/axiom/setup).
16
17 ## Install the Axiom provider
18
19 ```sh
20 bun add @alchemy.run/axiom
21 ```
22
23 ## Let the stack create Axiom resources
24
25 ```diff lang="typescript"
26 // alchemy.run.ts
27 import * as Alchemy from "alchemy";
28 +import * as Axiom from "@alchemy.run/axiom";
29 import * as Cloudflare from "@alchemy.run/cloudflare";
30 import * as Effect from "effect/Effect";
31 +import * as Layer from "effect/Layer";
32 import BankWorker from "./src/BankWorker.ts";
33
34 export default Alchemy.Stack(
35 "Bank",
36 - { providers: Cloudflare.providers(), state: Cloudflare.state() },
37 + {
38 + providers: Layer.mergeAll(Cloudflare.providers(), Axiom.providers()),
39 + state: Cloudflare.state(),
40 + },
41 Effect.gen(function* () {
42 const bank = yield* BankWorker;
43 const app = yield* Cloudflare.Website.Foldkit("BankApp", {
44 main: "src/web/worker.ts",
45 env: { BANK: bank },
46 assets: { runWorkerFirst: ["/api", "/api/*"] },
47 });
48 return { url: bank.url.as<string>(), app: app.url.as<string>() };
49 }),
50 );
51 ```
52
53 `Axiom.providers()` sits next to `Cloudflare.providers()`, so the stack can create Axiom datasets and tokens alongside the bank.
54
55 ## Create the datasets and an ingest token
56
57 ```typescript
58 // src/Observability.ts
59 import * as Axiom from "@alchemy.run/axiom";
60
61 // Where spans go.
62 export const Traces = Axiom.Dataset("Traces", {
63 name: "bank-traces",
64 kind: "otel:traces:v1",
65 });
66
67 // Where logs go.
68 export const Logs = Axiom.Dataset("Logs", {
69 name: "bank-logs",
70 kind: "otel:logs:v1",
71 });
72
73 // A token that may write to those two datasets, and nothing else.
74 export const Ingest = Axiom.ApiToken("Ingest", {
75 name: "bank-ingest",
76 datasetCapabilities: {
77 "bank-traces": { ingest: ["create"] },
78 "bank-logs": { ingest: ["create"] },
79 },
80 });
81 ```
82
83 These are three Axiom resources. The stack creates them the first time a Worker uses them.
84
85 :::note
86 Dataset names are global to your Axiom org. If you deploy more than one stage, give each its own datasets: see [per-stage datasets](/axiom/data/ingest#per-stage-datasets).
87 :::
88
89 ## Send the bank's telemetry to Axiom
90
91 ```diff lang="typescript"
92 // src/BankWorker.ts
93 +import * as Axiom from "@alchemy.run/axiom";
94 import * as Cloudflare from "@alchemy.run/cloudflare";
95 import * as DomainCloudflare from "@alchemy.run/cloudflare/Domain";
96 import * as Effect from "effect/Effect";
97 import { HttpServerRequest } from "effect/http/HttpServerRequest";
98 import * as Layer from "effect/Layer";
99 import { Bank, BankHandlers } from "./Bank.model.ts";
100 import { BankApi } from "./BankApi.api.ts";
101 +import { Ingest, Logs, Traces } from "./Observability.ts";
102 import { SessionLive, sessionRoute } from "./Session.middleware.ts";
103
104 -const BankLive = SessionLive.pipe(
105 +// Export every span and log to Axiom.
106 +const TelemetryLive = Axiom.Telemetry({
107 + token: Ingest,
108 + traces: Traces,
109 + logs: Logs,
110 + serviceName: "bank",
111 +});
112 +
113 +const BankLive = Layer.mergeAll(SessionLive, TelemetryLive).pipe(
114 Layer.provideMerge(Bank.layer(BankHandlers)),
115 Layer.provide(DomainCloudflare.layerDurableObjects()),
116 );
117
118 export default class BankWorker extends Cloudflare.Worker<BankWorker>()(
119 "BankWorker",
120 { main: import.meta.url },
121 Effect.gen(function* () {
122 const api = yield* BankApi;
123 return {
124 fetch: Effect.gen(function* () {
125 const request = yield* HttpServerRequest;
126 const path = new URL(request.url, "http://localhost").pathname;
127 return path === "/api/session" ? yield* sessionRoute : yield* api.fetch;
128 }),
129 };
130 }).pipe(Effect.provide(BankLive)),
131 ) {}
132 ```
133
134 This is the only change the bank needs. `Axiom.Telemetry` gives the Worker the datasets' addresses and the token, and the Worker and every Durable Object it hosts export their spans and logs after each response.
135
136 ## Follow a deposit
137
138 ```sh
139 bun alchemy deploy
140 ```
141
142 Open the app, deposit, and open `bank-traces` in Axiom. The deposit is one trace:
143
144 ```text
145 POST the bank's Worker received the request
146 └─ DepositMoney the Api ran the call
147 └─ Domain.send Account.DepositMoney the Worker sent the command to the account
148 └─ Domain.decide Account.DepositMoney the account's Durable Object decided and committed
149 │ event MoneyDeposited one span event per committed event
150 ├─ Domain.view AccountSummary the summary view applied the event
151 └─ Domain.view Statement the statement view applied the event
152 ```
153
154 The trace crosses the Worker and three Durable Objects. Each event carries the span that committed it, so the views that react to it continue the same trace.
155
156 ## See how a command ended
157
158 Every `Domain.decide` span records how its command ended in `domain.outcome`. Your deposit reads `accepted`. A withdrawal larger than the balance reads `InsufficientFunds`, the tag of its rejection. A rejection is an answer, not a failure, so the span still ends cleanly; only a defect marks it as failed.
159
160 ## Follow a flow across traces
161
162 Registering a customer opens their account through the `MainAccountProvisioning` policy. The policy runs after the registration commits, so it starts its own trace, linked to the one that caused it.
163
164 Every span carries `domain.correlation_id`, the id of the first command in the flow. Filter on it to see the registration, the policy and the account opening together.
165
166 ## Record the amount on every withdrawal
167
168 ```diff lang="typescript"
169 // src/WithdrawMoney.command.ts
170 import * as Domain from "@alchemy.run/domain";
171 import * as Schema from "effect/Schema";
172 import { AccountId } from "./Account.id.ts";
173 import { NotOpen } from "./NotOpen.rejection.ts";
174 import { NotOwner } from "./NotOwner.rejection.ts";
175 import { Session } from "./Session.middleware.ts";
176
177 export class MoneyWithdrawn extends Domain.Event("MoneyWithdrawn", {
178 amount: Schema.Int,
179 balanceAfter: Schema.Int,
180 }) {}
181
182 export class InsufficientFunds extends Domain.Rejection("InsufficientFunds", {
183 balance: Schema.Int,
184 requested: Schema.Int,
185 }) {}
186
187 export class WithdrawMoney extends Domain.Command("WithdrawMoney", {
188 target: AccountId,
189 middleware: [Session],
190 input: { amount: Schema.Int },
191 events: [MoneyWithdrawn],
192 rejects: [NotOpen, NotOwner, InsufficientFunds],
193 reply: { balance: Schema.Int },
194 + attributes: (cmd) => ({ "bank.amount": cmd.amount }),
195 }) {}
196 ```
197
198 Spans record nothing from a command's input unless you ask. `attributes` adds `bank.amount` to every span the withdrawal makes, so you can find large withdrawals in Axiom. Events and rejections accept `attributes` too, and a `Redacted` value is always recorded as `<redacted>`.
199
200 ## Trace the browser
201
202 The bank is traced. The trace still starts at the Worker, though, not at the click that caused it. The rest of this part adds the browser's spans.
203
204 The browser can't send to Axiom itself: that would put the ingest token in every visitor's hands. Instead it sends its spans to the bank's Worker, and the Worker forwards them to Axiom with its own token.
205
206 ## Export the sign-in check
207
208 ```diff lang="typescript"
209 // src/Session.middleware.ts
210 -const signedIn = (headers: Headers.Headers): Option.Option<string> =>
211 +export const signedIn = (headers: Headers.Headers): Option.Option<string> =>
212 ```
213
214 The Worker will forward spans only from signed-in customers, so a stranger can't fill your dataset. Export the `signedIn` check from Part 6 so it can use it.
215
216 ## Forward the browser's spans to Axiom
217
218 ```diff lang="typescript"
219 // src/BankWorker.ts
220 import * as Axiom from "@alchemy.run/axiom";
221 import * as Cloudflare from "@alchemy.run/cloudflare";
222 import * as DomainCloudflare from "@alchemy.run/cloudflare/Domain";
223 +import * as Telemetry from "alchemy/Telemetry";
224 import * as Effect from "effect/Effect";
225 import { HttpServerRequest } from "effect/http/HttpServerRequest";
226 import * as Layer from "effect/Layer";
227 +import * as Option from "effect/Option";
228 import { Bank, BankHandlers } from "./Bank.model.ts";
229 import { BankApi } from "./BankApi.api.ts";
230 import { Ingest, Logs, Traces } from "./Observability.ts";
231 -import { SessionLive, sessionRoute } from "./Session.middleware.ts";
232 +import { SessionLive, sessionRoute, signedIn } from "./Session.middleware.ts";
233
234 // Export every span and log to Axiom.
235 const TelemetryLive = Axiom.Telemetry({
236 token: Ingest,
237 traces: Traces,
238 logs: Logs,
239 serviceName: "bank",
240 });
241
242 const BankLive = Layer.mergeAll(SessionLive, TelemetryLive).pipe(
243 Layer.provideMerge(Bank.layer(BankHandlers)),
244 Layer.provide(DomainCloudflare.layerDurableObjects()),
245 );
246
247 +// Accepts spans from the browser and forwards them to Axiom, for signed-in customers only.
248 +const relayBrowserSpans = Telemetry.relay({
249 + authorize: Effect.map(HttpServerRequest, (request) =>
250 + Option.isSome(signedIn(request.headers)),
251 + ),
252 +});
253 +
254 export default class BankWorker extends Cloudflare.Worker<BankWorker>()(
255 "BankWorker",
256 { main: import.meta.url },
257 Effect.gen(function* () {
258 const api = yield* BankApi;
259 return {
260 fetch: Effect.gen(function* () {
261 const request = yield* HttpServerRequest;
262 const path = new URL(request.url, "http://localhost").pathname;
263 - return path === "/api/session" ? yield* sessionRoute : yield* api.fetch;
264 + if (path === "/api/session") return yield* sessionRoute;
265 + if (path.startsWith("/api/telemetry/")) return yield* relayBrowserSpans;
266 + return yield* api.fetch;
267 }),
268 };
269 }).pipe(Effect.provide(BankLive)),
270 ) {}
271 ```
272
273 `Telemetry.relay` is an HTTP handler that receives spans and sends them wherever the Worker's own telemetry goes, which is Axiom. It lives under `/api`, so the app's Worker from Part 6 already forwards it to the bank.
274
275 ## Give the app a tracer
276
277 ```diff lang="typescript"
278 // src/web/entry.ts
279 import * as Domain from "@alchemy.run/domain";
280 import * as Effect from "effect/Effect";
281 import * as FetchHttpClient from "effect/http/FetchHttpClient";
282 import * as HttpClient from "effect/http/HttpClient";
283 import * as HttpClientRequest from "effect/http/HttpClientRequest";
284 import * as Layer from "effect/Layer";
285 +import * as OtlpSerialization from "effect/observability/OtlpSerialization";
286 +import * as OtlpTracer from "effect/observability/OtlpTracer";
287 import * as Socket from "effect/socket/Socket";
288 import { Runtime } from "foldkit";
289 import { BankApi } from "../BankApi.api.ts";
290 import { CustomerId } from "../Customer.id.ts";
291 import { Flags, init, Model, subscriptions, update, view } from "./Bank.ts";
292
293 // A stand-in for a login page: `?customer=c-2` picks who you are.
294 const customerId = CustomerId.make(new URLSearchParams(location.search).get("customer") ?? "c-1");
295
296 // Sign in, so the browser holds the session cookie for every call and watch.
297 const signIn = Effect.gen(function* () {
298 const client = HttpClient.filterStatusOk(yield* HttpClient.HttpClient);
299 yield* client.execute(
300 HttpClientRequest.post("/api/session").pipe(HttpClientRequest.bodyJsonUnsafe({ customerId })),
301 );
302 });
303
304 const BankConnection = Layer.unwrap(
305 signIn.pipe(
306 Effect.orDie,
307 Effect.as(
308 BankApi.layerClient.pipe(
309 Layer.provide(Domain.protocolWebSocket(`${location.origin}/api`)),
310 Layer.provide(Socket.layerWebSocketConstructorGlobal),
311 ),
312 ),
313 ),
314 -).pipe(Layer.provide(FetchHttpClient.layer));
315 +);
316 +
317 +// Send the app's spans to the bank's relay, on this origin.
318 +const Tracing = OtlpTracer.layer({
319 + url: `${location.origin}/api/telemetry/v1/traces`,
320 + resource: { serviceName: "bank-web" },
321 +}).pipe(Layer.provide(OtlpSerialization.layerJson));
322 +
323 +const Resources = Layer.mergeAll(BankConnection, Tracing).pipe(
324 + Layer.provide(FetchHttpClient.layer),
325 +);
326
327 Runtime.run(
328 Runtime.makeApplication({
329 Model,
330 Flags,
331 init,
332 update,
333 view,
334 subscriptions,
335 - resources: BankConnection,
336 + resources: Resources,
337 container: document.getElementById("root"),
338 }),
339 { flags: Effect.succeed({ customerId }) },
340 );
341 ```
342
343 `Tracing` is a standard OpenTelemetry exporter pointed at the relay. foldkit records a span for every command it runs, and every Api call carries the current trace to the bank.
344
345 ## Follow a click
346
347 ```sh
348 bun alchemy deploy
349 ```
350
351 Deposit again. The trace now starts in the browser:
352
353 ```text
354 Deposit the app ran its Deposit command
355 └─ DepositMoney the app's bank client made the call
356 └─ POST the browser sent the request
357 └─ POST the bank's Worker received it
358 └─ DepositMoney
359 └─ Domain.send Account.DepositMoney
360 └─ Domain.decide Account.DepositMoney
361 │ event MoneyDeposited
362 ├─ Domain.view AccountSummary
363 └─ Domain.view Statement
364 ```
365
366 One trace shows the click, the command it sent, and everything it changed.
367
368 :::note
369 Next, [change a deployed model](/domain/tutorial/part-8). Metrics, logs from handlers, and turning off view spans are in [Observability](/domain/observability). To get alerted on what you now record, see [Monitors & Alerting](/axiom/guides/alerting).
370 :::