1import type * as Credentials from "@distilled.cloud/aws/Credentials";
2import type * as SigV4 from "@distilled.cloud/aws/SigV4";
3import type * as Duration from "effect/Duration";
4import type * as Effect from "effect/Effect";
5import * as Binding from "../../Binding.ts";
6import type {
7 PrometheusApiError,
8 PrometheusInstantResult,
9 PrometheusRangeResult,
10 PrometheusTime,
11} from "./PrometheusTypes.ts";
12import type { Workspace } from "./Workspace.ts";
13
14export interface QueryMetricsRequest {
15 /** PromQL expression to evaluate, e.g. `up` or `rate(http_requests_total[5m])`. */
16 query: string;
17 /**
18 * Evaluation instant. A `Date`, Unix seconds, or an RFC 3339 string.
19 * @default the server's current time
20 */
21 time?: PrometheusTime;
22 /**
23 * Evaluation timeout. Capped by the server-side query timeout.
24 */
25 timeout?: Duration.Input;
26}
27
28export interface QueryRangeRequest {
29 /** PromQL expression to evaluate over the range. */
30 query: string;
31 /** Start of the range (inclusive). A `Date`, Unix seconds, or RFC 3339 string. */
32 start: PrometheusTime;
33 /** End of the range (inclusive). A `Date`, Unix seconds, or RFC 3339 string. */
34 end: PrometheusTime;
35 /** Resolution step between evaluated points, e.g. `"30 seconds"`. */
36 step: Duration.Input;
37 /** Evaluation timeout. Capped by the server-side query timeout. */
38 timeout?: Duration.Input;
39}
40
41export interface QueryMetricsClient {
42 /** Evaluate a PromQL expression at a single instant (`api/v1/query`). */
43 query(
44 request: QueryMetricsRequest,
45 ): Effect.Effect<
46 PrometheusInstantResult,
47 PrometheusApiError | Credentials.CredentialsError | SigV4.SigningError
48 >;
49 /** Evaluate a PromQL expression over a time range (`api/v1/query_range`). */
50 queryRange(
51 request: QueryRangeRequest,
52 ): Effect.Effect<
53 PrometheusRangeResult,
54 PrometheusApiError | Credentials.CredentialsError | SigV4.SigningError
55 >;
56}
57
58/**
59 * Runtime binding for `aps:QueryMetrics` — evaluate PromQL against an AMP
60 * {@link Workspace}'s Prometheus-compatible query API (`api/v1/query` and
61 * `api/v1/query_range`), SigV4-signed with the host Function's credentials.
62 *
63 * ### Querying Metrics
64 * **Example:** Instant Query
65 * ```typescript
66 * const metrics = yield* AMP.QueryMetrics(workspace);
67 *
68 * const result = yield* metrics.query({ query: "up" });
69 * if (result.resultType === "vector") {
70 * for (const sample of result.result) {
71 * console.log(sample.metric.__name__, sample.value[1]);
72 * }
73 * }
74 * ```
75 *
76 * **Example:** Range Query
77 * ```typescript
78 * const result = yield* metrics.queryRange({
79 * query: "rate(http_requests_total[5m])",
80 * start: new Date(Date.now() - 3_600_000),
81 * end: new Date(),
82 * step: "30 seconds",
83 * });
84 * ```
85 *
86 * @binding
87 */
88export interface QueryMetrics extends Binding.Service<
89 QueryMetrics,
90 "AWS.AMP.QueryMetrics",
91 (workspace: Workspace) => Effect.Effect<QueryMetricsClient>
92> {}
93export const QueryMetrics = Binding.Service<QueryMetrics>(
94 "AWS.AMP.QueryMetrics",
95);