1import type * as Credentials from "@distilled.cloud/aws/Credentials";
2import type * as SigV4 from "@distilled.cloud/aws/SigV4";
3import type * as Effect from "effect/Effect";
4import * as Binding from "../../Binding.ts";
5import type { PrometheusApiError } from "./PrometheusTypes.ts";
6import type { Workspace } from "./Workspace.ts";
7
8export interface RemoteWriteSample {
9 /** Sample value. */
10 value: number;
11 /**
12 * Sample timestamp in epoch **milliseconds**.
13 * @default the time of the remote-write call
14 */
15 timestamp?: number;
16}
17
18export interface RemoteWriteSeries {
19 /** Metric name (becomes the `__name__` label). */
20 name: string;
21 /** Additional labels for the series. */
22 labels?: Record<string, string>;
23 /** Samples to append, oldest first. */
24 samples: RemoteWriteSample[];
25}
26
27export interface RemoteWriteRequest {
28 /** Time series to write. */
29 timeseries: RemoteWriteSeries[];
30}
31
32/**
33 * Runtime binding for `aps:RemoteWrite` — push metric samples into an AMP
34 * {@link Workspace} via its Prometheus remote-write endpoint
35 * (`api/v1/remote_write`), SigV4-signed with the host Function's credentials.
36 *
37 * The protobuf + snappy remote-write body is encoded internally — callers
38 * pass plain metric names, labels, and samples.
39 *
40 * ### Writing Metrics
41 * **Example:** Push a Counter Sample
42 * ```typescript
43 * const remoteWrite = yield* AMP.RemoteWrite(workspace);
44 *
45 * yield* remoteWrite({
46 * timeseries: [{
47 * name: "jobs_processed_total",
48 * labels: { queue: "default" },
49 * samples: [{ value: 42 }],
50 * }],
51 * });
52 * ```
53 *
54 * **Example:** Backfill Samples with Explicit Timestamps
55 * ```typescript
56 * yield* remoteWrite({
57 * timeseries: [{
58 * name: "temperature_celsius",
59 * labels: { sensor: "a1" },
60 * samples: [
61 * { value: 20.1, timestamp: Date.now() - 60_000 },
62 * { value: 20.4, timestamp: Date.now() },
63 * ],
64 * }],
65 * });
66 * ```
67 *
68 * @binding
69 */
70export interface RemoteWrite extends Binding.Service<
71 RemoteWrite,
72 "AWS.AMP.RemoteWrite",
73 (
74 workspace: Workspace,
75 ) => Effect.Effect<
76 (
77 request: RemoteWriteRequest,
78 ) => Effect.Effect<
79 void,
80 PrometheusApiError | Credentials.CredentialsError | SigV4.SigningError
81 >
82 >
83> {}
84export const RemoteWrite = Binding.Service<RemoteWrite>("AWS.AMP.RemoteWrite");