1import type * as Logs from "@distilled.cloud/aws/cloudwatch-logs";
2import type * as Effect from "effect/Effect";
3import * as Binding from "../../Binding.ts";
4import type { LogGroup } from "./LogGroup.ts";
5
6export interface StartQueryRequest extends Omit<
7 Logs.StartQueryRequest,
8 "logGroupName" | "logGroupNames" | "logGroupIdentifiers"
9> {}
10
11/**
12 * Runtime binding for `logs:StartQuery` (CloudWatch Logs Insights).
13 *
14 * Bind this operation to a `LogGroup` inside a function runtime to get a
15 * callable that starts an Insights query scoped to the group, automatically
16 * injecting the log group name. Pair with
17 * {@link import("./GetQueryResults.ts").GetQueryResults} to poll for results.
18 * ### Logs Insights
19 * **Example:** Start an Insights Query
20 * ```typescript
21 * const startQuery = yield* AWS.Logs.StartQuery(logGroup);
22 *
23 * const { queryId } = yield* startQuery({
24 * queryString: "fields @timestamp, @message | limit 10",
25 * startTime: startEpochSeconds,
26 * endTime: endEpochSeconds,
27 * });
28 * ```
29 *
30 * **Example:** Wire into a Lambda Function
31 * ```typescript
32 * // Insights queries are asynchronous: start one, then poll with the
33 * // GetQueryResults binding. Provide both HTTP layers with Layer.mergeAll.
34 * export default InsightsFunction.make(
35 * { main: import.meta.url, functionUrl: true },
36 * Effect.gen(function* () {
37 * const logGroup = yield* AWS.Logs.LogGroup("AppLogs", {});
38 * const startQuery = yield* AWS.Logs.StartQuery(logGroup);
39 * const getQueryResults = yield* AWS.Logs.GetQueryResults(logGroup);
40 * return {
41 * fetch: Effect.gen(function* () {
42 * const now = yield* Clock.currentTimeMillis;
43 * const { queryId } = yield* startQuery({
44 * queryString: "fields @timestamp, @message | limit 10",
45 * startTime: Math.floor(now / 1000) - 3600,
46 * endTime: Math.floor(now / 1000),
47 * });
48 * return HttpServerResponse.json({ queryId });
49 * }),
50 * };
51 * }).pipe(
52 * Effect.provide(
53 * Layer.mergeAll(AWS.Logs.StartQueryHttp, AWS.Logs.GetQueryResultsHttp),
54 * ),
55 * ),
56 * );
57 * ```
58 *
59 * @binding
60 */
61export interface StartQuery extends Binding.Service<
62 StartQuery,
63 "AWS.Logs.StartQuery",
64 <G extends LogGroup>(
65 logGroup: G,
66 ) => Effect.Effect<
67 (
68 request: StartQueryRequest,
69 ) => Effect.Effect<Logs.StartQueryResponse, Logs.StartQueryError>
70 >
71> {}
72export const StartQuery = Binding.Service<StartQuery>("AWS.Logs.StartQuery");