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
| 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 | ::: |