The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as Clock from "effect/Clock"; |
| 2 | import * as Duration from "effect/Duration"; |
| 3 | import * as Effect from "effect/Effect"; |
| 4 | import * as Exit from "effect/Exit"; |
| 5 | import * as Metric from "effect/Metric"; |
| 6 | import { dual } from "effect/Function"; |
| 7 | |
| 8 | import { compactMetricAttributes, outcomeFromExit } from "./Attributes.ts"; |
| 9 | |
| 10 | export const rpcRequestsTotal = Metric.counter("t3_rpc_requests_total", { |
| 11 | description: "Total RPC requests handled by the websocket RPC server.", |
| 12 | }); |
| 13 | |
| 14 | export const rpcRequestDuration = Metric.timer("t3_rpc_request_duration", { |
| 15 | description: "RPC request handling duration.", |
| 16 | }); |
| 17 | |
| 18 | export const orchestrationCommandsTotal = Metric.counter("t3_orchestration_commands_total", { |
| 19 | description: "Total orchestration commands dispatched, by outcome.", |
| 20 | }); |
| 21 | |
| 22 | export const orchestrationCommandDuration = Metric.timer("t3_orchestration_command_duration", { |
| 23 | description: "Orchestration command handling duration, excluding thread dispatch lock wait.", |
| 24 | }); |
| 25 | |
| 26 | export const orchestrationEffectClaimsTotal = Metric.counter( |
| 27 | "t3_orchestration_effect_claims_total", |
| 28 | { |
| 29 | description: "Total completed orchestration effect outbox claim attempts by result.", |
| 30 | }, |
| 31 | ); |
| 32 | |
| 33 | export const orchestrationEffectQueueWait = Metric.timer("t3_orchestration_effect_queue_wait", { |
| 34 | description: |
| 35 | "Time from an orchestration effect's temporal availability until claim, including same-thread blocking.", |
| 36 | }); |
| 37 | |
| 38 | // A failed batch (transport errors and 408/429/500/502/503/504 after 3 retries) is dropped with |
| 39 | // every push for the next 60 s, logged only at Debug. Incremental exports it as a monotonic counter. |
| 40 | export const otlpExportAttemptFailuresTotal = Metric.counter( |
| 41 | "t3_otlp_export_attempt_failures_total", |
| 42 | { |
| 43 | description: |
| 44 | "Failed OTLP export attempts by signal and reason. Retries count too, so a dropped batch counts up to four.", |
| 45 | incremental: true, |
| 46 | }, |
| 47 | ); |
| 48 | |
| 49 | export const providerSessionsTotal = Metric.counter("t3_provider_sessions_total", { |
| 50 | description: "Total provider session lifecycle operations.", |
| 51 | }); |
| 52 | |
| 53 | export const providerTurnsTotal = Metric.counter("t3_provider_turns_total", { |
| 54 | description: "Total provider turn lifecycle operations.", |
| 55 | }); |
| 56 | |
| 57 | export const providerTurnDuration = Metric.timer("t3_provider_turn_duration", { |
| 58 | description: "Time for the provider adapter to start a turn, not how long the turn runs.", |
| 59 | }); |
| 60 | |
| 61 | // OTLP carries the unit, and Prometheus names the series by it: a unitless gauge gains `_ratio`. |
| 62 | export const serverResidentBytes = Metric.gauge("t3_server_resident_bytes", { |
| 63 | description: "Resident memory of the server process.", |
| 64 | attributes: { unit: "By" }, |
| 65 | }); |
| 66 | |
| 67 | export const serverHeapUsedBytes = Metric.gauge("t3_server_heap_used_bytes", { |
| 68 | description: "JavaScript heap in use by the server process.", |
| 69 | attributes: { unit: "By" }, |
| 70 | }); |
| 71 | |
| 72 | export const serverCpuUtilization = Metric.gauge("t3_server_cpu_utilization", { |
| 73 | description: "CPU time the server used per second over the last sample; 1 is one full core.", |
| 74 | }); |
| 75 | |
| 76 | export const serverEventLoopUtilization = Metric.gauge("t3_server_event_loop_utilization", { |
| 77 | description: "Share of the last sample the server's event loop spent busy.", |
| 78 | }); |
| 79 | |
| 80 | export const serverEventLoopDelayMax = Metric.gauge("t3_server_event_loop_delay_max", { |
| 81 | description: "Longest event loop delay over the last sample.", |
| 82 | attributes: { unit: "ms" }, |
| 83 | }); |
| 84 | |
| 85 | export const runsTotal = Metric.counter("t3_runs_total", { |
| 86 | description: "Runs that finished, by outcome. A later rollback does not count again.", |
| 87 | }); |
| 88 | |
| 89 | export const runDuration = Metric.timer("t3_run_duration", { |
| 90 | description: "Wall time of a run, from when it started to its terminal status.", |
| 91 | }); |
| 92 | |
| 93 | export const runQueueWait = Metric.timer("t3_run_queue_wait", { |
| 94 | description: "Time a run waited between being requested and starting.", |
| 95 | }); |
| 96 | |
| 97 | export const gitCommandsTotal = Metric.counter("t3_git_commands_total", { |
| 98 | description: "Total git commands executed by the server runtime.", |
| 99 | }); |
| 100 | |
| 101 | export const gitCommandDuration = Metric.timer("t3_git_command_duration", { |
| 102 | description: "Git command execution duration.", |
| 103 | }); |
| 104 | |
| 105 | export const terminalSessionsTotal = Metric.counter("t3_terminal_sessions_total", { |
| 106 | description: "Total terminal sessions started.", |
| 107 | }); |
| 108 | |
| 109 | export const webhookDeliveriesTotal = Metric.counter("t3_webhook_deliveries_total", { |
| 110 | description: "Webhook requests handled, by outcome and source.", |
| 111 | }); |
| 112 | |
| 113 | export const webhookDeliveryDuration = Metric.timer("t3_webhook_delivery_duration", { |
| 114 | description: "Time to verify, log, and enqueue one webhook request.", |
| 115 | }); |
| 116 | |
| 117 | export const webhookHeldDelay = Metric.timer("t3_webhook_held_delay", { |
| 118 | description: |
| 119 | "Time between the relay receiving a webhook request and the environment handling it.", |
| 120 | }); |
| 121 | |
| 122 | export const webhookRunsTotal = Metric.counter("t3_webhook_runs_total", { |
| 123 | description: "Runs started from webhook deliveries, by outcome.", |
| 124 | }); |
| 125 | |
| 126 | export const secretRequestsTotal = Metric.counter("t3_secret_requests_total", { |
| 127 | description: "Secrets agents asked users for, by how each request ended.", |
| 128 | }); |
| 129 | |
| 130 | export const secretRefsConsumedTotal = Metric.counter("t3_secret_refs_consumed_total", { |
| 131 | description: "Secret refs tools tried to use, by result.", |
| 132 | }); |
| 133 | |
| 134 | export const metricAttributes = ( |
| 135 | attributes: Readonly<Record<string, unknown>>, |
| 136 | ): ReadonlyArray<[string, string]> => Object.entries(compactMetricAttributes(attributes)); |
| 137 | |
| 138 | export const increment = ( |
| 139 | metric: Metric.Metric<number, unknown>, |
| 140 | attributes: Readonly<Record<string, unknown>>, |
| 141 | amount = 1, |
| 142 | ) => Metric.update(Metric.withAttributes(metric, metricAttributes(attributes)), amount); |
| 143 | |
| 144 | export interface WithMetricsOptions { |
| 145 | readonly counter?: Metric.Metric<number, unknown>; |
| 146 | readonly timer?: Metric.Metric<Duration.Duration, unknown>; |
| 147 | readonly attributes?: |
| 148 | | Readonly<Record<string, unknown>> |
| 149 | | (() => Readonly<Record<string, unknown>>); |
| 150 | readonly outcomeAttributes?: ( |
| 151 | outcome: ReturnType<typeof outcomeFromExit>, |
| 152 | ) => Readonly<Record<string, unknown>>; |
| 153 | } |
| 154 | |
| 155 | const recordMetrics = |
| 156 | /* Instrumentation must not create its own span for every recorded operation. */ |
| 157 | Effect.fnUntraced(function* ( |
| 158 | options: WithMetricsOptions, |
| 159 | startedAt: bigint, |
| 160 | exit: Exit.Exit<unknown, unknown>, |
| 161 | ) { |
| 162 | const duration = Duration.nanos((yield* Clock.monotonicTimeNanos) - startedAt); |
| 163 | const baseAttributes = |
| 164 | typeof options.attributes === "function" ? options.attributes() : (options.attributes ?? {}); |
| 165 | |
| 166 | if (options.timer) { |
| 167 | yield* Metric.update( |
| 168 | Metric.withAttributes(options.timer, metricAttributes(baseAttributes)), |
| 169 | duration, |
| 170 | ); |
| 171 | } |
| 172 | |
| 173 | if (options.counter) { |
| 174 | const outcome = outcomeFromExit(exit); |
| 175 | yield* Metric.update( |
| 176 | Metric.withAttributes( |
| 177 | options.counter, |
| 178 | metricAttributes({ |
| 179 | ...baseAttributes, |
| 180 | outcome, |
| 181 | ...(options.outcomeAttributes ? options.outcomeAttributes(outcome) : {}), |
| 182 | }), |
| 183 | ), |
| 184 | 1, |
| 185 | ); |
| 186 | } |
| 187 | }); |
| 188 | |
| 189 | // Monotonic timing ignores clock corrections; exit finalizers count interruptions. |
| 190 | const withMetricsImpl = <A, E, R>( |
| 191 | effect: Effect.Effect<A, E, R>, |
| 192 | options: WithMetricsOptions, |
| 193 | ): Effect.Effect<A, E, R> => |
| 194 | Effect.flatMap(Clock.monotonicTimeNanos, (startedAt) => |
| 195 | Effect.onExit(effect, (exit) => recordMetrics(options, startedAt, exit)), |
| 196 | ); |
| 197 | |
| 198 | export const withMetrics: { |
| 199 | ( |
| 200 | options: WithMetricsOptions, |
| 201 | ): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>; |
| 202 | <A, E, R>(effect: Effect.Effect<A, E, R>, options: WithMetricsOptions): Effect.Effect<A, E, R>; |
| 203 | } = dual(2, withMetricsImpl); |
| 204 | |
| 205 | // Shaped as an `Effect.fn` combinator: the command is the instrumented function's argument. |
| 206 | export const withCommandMetrics = <A, E, R>( |
| 207 | effect: Effect.Effect<A, E, R>, |
| 208 | command: { readonly type: string }, |
| 209 | ): Effect.Effect<A, E, R> => |
| 210 | withMetrics(effect, { |
| 211 | counter: orchestrationCommandsTotal, |
| 212 | timer: orchestrationCommandDuration, |
| 213 | attributes: { commandType: command.type }, |
| 214 | }); |