@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, 06:00 UTC

main
mdx 216 lines 8.11 KB
Raw
1 ---
2 title: Telemetry
3 description: OpenTelemetry is built into every runtime — exporters are Layers, wired to resources through the binding infrastructure, built per event, and flushed as each request completes.
4 ---
5
6 Every Alchemy runtime ships with OpenTelemetry export built in.
7 Each fetch, queue message, cron fire, RPC call, Durable Object call,
8 Workflow run, and Lambda invocation is wrapped in the machinery to
9 export the traces, logs, and metrics that Effect already emits —
10 `Effect.withSpan` and `Effect.fn` spans, `Effect.log` records, and
11 `Metric` updates. There is no SDK to initialize: the exporter is a
12 Layer, configured like everything else in Alchemy.
13
14 ## Provide an exporter layer
15
16 Telemetry is configured by providing a Layer on the Runtime's
17 constructor Effect, merged into the single `Effect.provide` alongside the
18 other binding layers:
19
20 ```typescript
21 import * as Alchemy from "alchemy";
22 import * as Axiom from "@alchemy.run/axiom";
23
24 export default Cloudflare.Worker(
25 "Worker",
26 { main: import.meta.url },
27 Effect.gen(function* () {
28 // ...
29 }).pipe(
30 Effect.provide(
31 Layer.mergeAll(
32 Cloudflare.R2.ReadWriteBucketBinding,
33 Axiom.Telemetry({ token: Ingest, traces: Traces, logs: Logs }),
34 ),
35 ),
36 ),
37 );
38 ```
39
40 Without a telemetry layer, nothing exports — Effect's default tracer
41 is a no-op, so all instrumentation stays free.
42
43 On Cloudflare, [`Cloudflare.Telemetry()`](/cloudflare/observability/workers-tracing)
44 is the platform-native alternative: it mirrors Effect spans into
45 Workers Observability (fetch/KV/R2/D1 auto-spans included) instead of
46 shipping OTLP from the Worker. Cloudflare owns sampling and export.
47
48 ## Binding layers
49
50 `Alchemy.Telemetry.layerOtlp` is the generic form: a *binding* layer for
51 any OTLP/HTTP backend. Its url and header values accept plain values
52 or resource Outputs — at deploy time, building the layer binds them
53 onto the host (`Redacted` values as secret bindings), and at runtime
54 the exporter reads them back:
55
56 ```typescript
57 Alchemy.Telemetry.layerOtlp({
58 url: "https://api.honeycomb.io",
59 headers: { "x-honeycomb-team": apiKey },
60 })
61 ```
62
63 Each signal can also be configured independently — a per-signal
64 entry takes precedence over the base `url` (which gets
65 `/v1/{traces,logs,metrics}` appended):
66
67 ```typescript
68 Alchemy.Telemetry.layerOtlp({
69 traces: { url: collector.tracesUrl, headers: { ... } },
70 logs: { url: collector.logsUrl, headers: { ... } },
71 })
72 ```
73
74 Vendor layers wrap this. [`Axiom.Telemetry`](/axiom) takes an ingest
75 `ApiToken` and a `Dataset` per signal, and composes the endpoints and
76 `Authorization` and dataset (`X-Axiom-Dataset`, or `X-Axiom-Metrics-Dataset`
77 for metrics) headers for you — see
78 [Tutorial Part 6](/cloudflare/tutorial/part-6) for the end-to-end
79 walkthrough.
80
81 For a manually-configured backend — a url and an API key — resolve
82 the secret with `Config` in the layer's constructor and pass it as a header.
83 The `Config` read binds the value at deploy time, and because it is
84 `Redacted` it travels as a secret binding:
85
86 ```typescript
87 const Honeycomb = Layer.unwrap(
88 Effect.gen(function* () {
89 const key = yield* Config.Redacted("HONEYCOMB_API_KEY");
90 return Alchemy.Telemetry.layerOtlp({
91 url: "https://api.honeycomb.io",
92 headers: { "x-honeycomb-team": key },
93 });
94 }),
95 );
96 ```
97
98 ## Multiple destinations
99
100 Exporter layers compose: merge as many as you need and every
101 destination receives the telemetry. Telemetry is serialized once and
102 fanned out per signal, so trace and span ids agree across
103 destinations — the same trace is queryable in both backends:
104
105 ```typescript
106 Effect.provide(
107 Layer.mergeAll(
108 Cloudflare.R2.ReadWriteBucketBinding,
109 Axiom.Telemetry({ token: Ingest, traces: Traces, logs: Logs }),
110 Alchemy.Telemetry.layerOtlp({
111 url: "https://collector.internal.example.com",
112 headers: { "x-api-key": apiKey },
113 }),
114 ),
115 )
116 ```
117
118 Each destination only receives the signals it configures — here Axiom
119 gets traces and logs while the second collector gets all three. A
120 destination that fails to accept an export is logged and skipped; one
121 healthy destination keeps the exporter alive.
122
123 ## Service identity
124
125 The exported `service.name` defaults to the deployed Function/Worker's
126 physical name, then the stack name; set `serviceName` on the layer to
127 override it. Every signal also carries `alchemy.stack` and
128 `alchemy.stage` resource attributes, so one backend can receive every
129 stage and still tell them apart.
130
131 ## Per-event scope and flushing
132
133 On the per-event runtimes — Worker fetch/queue/cron/RPC, Durable
134 Object calls, Workflow runs, Lambda invocations — the exporters are
135 built into each event's request scope and buffered telemetry is
136 flushed when that scope closes:
137
138 - On Cloudflare, the flush is registered with `ctx.waitUntil`, so it
139 happens after the response is sent and never adds latency.
140 - On Lambda, the flush settles inline before the invocation returns —
141 the response isn't released until the invoke completes anyway. An
142 invocation that runs past its `timeout` is interrupted, so its
143 finalizers run and its spans end, and Lambda's extra `timeoutMargin`
144 gives the flush time to finish. If cleanup is still running 500 ms
145 before Lambda kills the invocation, the root span is ended and the
146 exporters drained early, so the trace arrives anyway.
147
148 This per-event lifecycle is what makes export work on workerd, where
149 timers and fetches are pinned to the request that created them: a
150 process-global batching exporter would be killed the moment its
151 creating request ended.
152
153 Server runtimes — Cloudflare Containers, ECS Tasks, EC2 hosts,
154 Lambda microVMs — are long-lived processes, so they build the
155 exporters once at startup instead: telemetry batches on the standard
156 export intervals and the final flush runs at graceful shutdown.
157
158 ## HTTP request spans
159
160 Fetch handlers get an `http.server` root span automatically, carrying
161 the method, URL, status, and headers. Incoming `traceparent` headers
162 are honored, so a trace that starts in one service continues through
163 your Worker or Lambda — and outgoing requests made with Effect's
164 `HttpClient` propagate the context onward.
165
166 Everything you instrument nests under that root:
167
168 ```typescript
169 const object = yield* bucket
170 .get(key)
171 .pipe(Effect.withSpan("bucket.get", { attributes: { key } }));
172 ```
173
174 ## Custom exporters
175
176 `Alchemy.Telemetry.layer` installs any Layer that provides a
177 `Tracer`, loggers, or metric exporters — Effect's
178 `effect/observability` modules (`OtlpTracer`, `OtlpLogger`,
179 `OtlpMetrics`, protobuf serialization) compose here directly. The
180 Layer is built per event into the event's request scope, so a custom
181 exporter gets the same flush-on-close behavior as the built-in one.
182
183 Custom layers also compose with the OTLP destinations and with each
184 other: loggers and metric exporters merge, while a custom `Tracer` —
185 a single Effect service — replaces the built-in one.
186
187 :::caution
188 A custom Layer for per-event runtimes should disable or greatly
189 lengthen its periodic export intervals (e.g.
190 `exportInterval: "1 hour"`). An interval export that fires mid-event
191 races the scope close — the close interrupts the in-flight batch and
192 drops it. The built-in exporter already handles this; the flush on
193 scope close delivers everything.
194 :::
195
196 ## Under the hood
197
198 The binding travels as environment bindings on the host: each
199 `layerOtlp` layer appends its destination to a single bound
200 destination list (secrets through the secret channel), and the
201 runtime exporter reads the list back per event. An environment that
202 sets the standard `OTEL_EXPORTER_OTLP_*` variables contributes one
203 implicit extra destination — useful when the platform injects OTLP
204 settings for you.
205
206 ## Where next
207
208 - [Tutorial Part 6](/cloudflare/tutorial/part-6) — bind a Worker's
209 telemetry to Axiom end to end
210 - [Observability](/testing/observability) — provision the receiving
211 end (datasets, tokens, monitors, alarms) as resources
212 - [Native Workers tracing](/cloudflare/observability/workers-tracing) —
213 `Cloudflare.Telemetry()`, Effect spans in the Cloudflare waterfall
214 - [Ship Worker telemetry to Axiom](/cloudflare/observability/axiom-observability) —
215 the Cloudflare-specific reference, including the platform-push
216 alternative