@alchemy.run/axiom 0.0.0 → 2.0.0-beta.84

package/src/Telemetry.ts

@@ -0,0 +1,116 @@
+import type { Input } from "alchemy/Input";
+import * as Output from "alchemy/Output";
+import { layerOtlp, type OtlpSignalOptions } from "alchemy/Telemetry";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import type { ApiToken } from "./ApiToken.ts";
+import type { Dataset } from "./Dataset.ts";
+import { otelDatasetHeader } from "./OtelHeaders.ts";
+
+/**
+ * A resource passed to the layer: either the module-scope declaration (an
+ * Effect that resolves to the instance, same as what capability bindings
+ * accept) or an already-yielded instance.
+ */
+export type ResourceInput<T> = T | Effect.Effect<T, never, any>;
+
+/**
+ * Options for {@link Telemetry}: an ingest {@link ApiToken} plus one
+ * {@link Dataset} per OTel signal to export.
+ */
+export interface AxiomTelemetryProps {
+  /**
+   * The ingest credential. Must have `ingest: ["create"]` capability on
+   * every dataset passed below.
+   */
+  token: ResourceInput<ApiToken>;
+  /** Dataset (kind `otel:traces:v1`) to export traces into. */
+  traces?: ResourceInput<Dataset> | undefined;
+  /** Dataset (kind `otel:logs:v1`) to export logs into. */
+  logs?: ResourceInput<Dataset> | undefined;
+  /** Dataset (kind `otel:metrics:v1`) to export metrics into. */
+  metrics?: ResourceInput<Dataset> | undefined;
+  /**
+   * The exported `service.name`.
+   * @default the deployed Function/Worker's physical name
+   */
+  serviceName?: Input<string> | undefined;
+}
+
+/**
+ * Resource declarations are Effects — yield them to get the instance with
+ * attribute Output accessors, same as `Binding.Service`'s callable does for
+ * capability bindings.
+ */
+const instance = <T>(resource: ResourceInput<T>): Effect.Effect<T> =>
+  Effect.isEffect(resource) ? (resource as Effect.Effect<T>) : Effect.succeed(resource);
+
+const signal = (
+  token: ApiToken,
+  dataset: Dataset | undefined,
+  urlAttr: "otelTracesEndpoint" | "otelLogsEndpoint" | "otelMetricsEndpoint",
+): OtlpSignalOptions | undefined =>
+  dataset === undefined
+    ? undefined
+    : {
+        url: dataset[urlAttr],
+        headers: {
+          Authorization: Output.map(
+            token.token,
+            (bearer) =>
+              Redacted.make(`Bearer ${Redacted.value(bearer)}`) as Redacted.Redacted<string>,
+          ),
+          [otelDatasetHeader(urlAttr === "otelMetricsEndpoint")]: dataset.name,
+        },
+      };
+
+/**
+ * Export a Function/Worker's telemetry to Axiom.
+ *
+ * A binding layer over {@link layerOtlp | Alchemy.Telemetry.layerOtlp}:
+ * building it binds each dataset's OTLP endpoint and the ingest token's
+ * `Authorization` header (as a secret) onto the host, and at runtime the
+ * built-in exporter ships each signal to its dataset, flushed per event.
+ *
+ * Compose it into the Function/Worker's single `Effect.provide`:
+ *
+ * ```ts
+ * import * as Axiom from "@alchemy.run/axiom";
+ * import { Bucket } from "./bucket.ts";
+ * import { Ingest, Logs, Traces } from "./observability.ts";
+ *
+ * export default Cloudflare.Worker(
+ *   "Worker",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     // ...
+ *   }).pipe(
+ *     Effect.provide(
+ *       Layer.mergeAll(
+ *         Cloudflare.R2.ReadWriteBucketBinding,
+ *         Axiom.Telemetry({ token: Ingest, traces: Traces, logs: Logs }),
+ *       ),
+ *     ),
+ *   ),
+ * );
+ * ```
+ */
+export const Telemetry = (props: AxiomTelemetryProps): Layer.Layer<never> =>
+  Layer.unwrap(
+    Effect.gen(function* () {
+      // Declarations are yielded to instances (registering them on the
+      // Stack if the enclosing host is the first to reference them), so
+      // attribute accessors below produce real Outputs.
+      const token = yield* instance(props.token);
+      const traces = props.traces && (yield* instance(props.traces));
+      const logs = props.logs && (yield* instance(props.logs));
+      const metrics = props.metrics && (yield* instance(props.metrics));
+      return layerOtlp({
+        serviceName: props.serviceName,
+        traces: signal(token, traces, "otelTracesEndpoint"),
+        logs: signal(token, logs, "otelLogsEndpoint"),
+        metrics: signal(token, metrics, "otelMetricsEndpoint"),
+      });
+    }),
+  ) as Layer.Layer<never>;

package/src/View.ts

@@ -0,0 +1,130 @@
+import * as Axiom from "@distilled.cloud/axiom";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import type { Providers } from "./Providers.ts";
+
+export type ViewProps = Axiom.CreateViewRequest;
+
+export type View = Resource<
+  "Axiom.View",
+  ViewProps,
+  Axiom.View & {
+    /**
+     * Path identifier used by `updateView` / `getView` / `deleteView`.
+     * Currently derived from `name` because Axiom's view list/get responses
+     * don't expose a separate id field.
+     */
+    id: string;
+  },
+  never,
+  Providers
+>;
+
+/**
+ * An Axiom saved view — a named, shareable APL query. Useful for building
+ * starter dashboards, providing canned "open in Axiom" links from your app,
+ * or pinning common investigations the team revisits.
+ *
+ * The path identifier is `name`. Renaming a view triggers a replacement
+ * (the old one is deleted, a new one is created).
+ * @see https://axiom.co/docs/query-data/datasets — APL query reference
+ *
+ * ### Creating a View
+ * **Example:** Recent errors across one dataset
+ * ```typescript
+ * yield* Axiom.View("recent-errors", {
+ *   name: "recent-errors",
+ *   description: "Last 100 5xx responses",
+ *   datasets: ["my-app-traces"],
+ *   aplQuery: `
+ *     ['my-app-traces']
+ *     | where status >= 500
+ *     | order by _time desc
+ *     | take 100
+ *   `,
+ * });
+ * ```
+ *
+ * **Example:** Cross-dataset join (logs + traces by trace_id)
+ * ```typescript
+ * yield* Axiom.View("trace-with-logs", {
+ *   name: "trace-with-logs",
+ *   datasets: ["my-app-traces", "my-app-logs"],
+ *   aplQuery: `
+ *     ['my-app-traces']
+ *     | where duration_ms > 1000
+ *     | join kind=leftouter (['my-app-logs']) on trace_id
+ *   `,
+ * });
+ * ```
+ *
+ * @resource
+ * @product Dashboard
+ */
+export const View = Resource<View>("Axiom.View");
+
+export const ViewProvider = () =>
+  Provider.effect(
+    View,
+    Effect.gen(function* () {
+      const create = yield* Axiom.createView;
+      const update = yield* Axiom.updateView;
+      const get = yield* Axiom.getView;
+      const listViews = yield* Axiom.getViews;
+      const del = yield* Axiom.deleteView;
+
+      return {
+        stables: ["id"],
+        // Enumerate every view in the org. Axiom exposes a single account-wide
+        // `GET /v2/views` collection op (no pagination) that already returns
+        // the full view objects, so we fetch it once and hydrate each row into
+        // the exact `read` Attributes shape (`id` is derived from `name`, the
+        // path identifier) — directly usable by `delete` with no follow-up get.
+        list: () =>
+          Effect.gen(function* () {
+            const views = yield* listViews({});
+            return views.map((view) => ({ ...view, id: view.name }));
+          }),
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          if (output && news.name !== output.name) {
+            return { action: "replace" } as const;
+          }
+          return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ news, output }) {
+          // Observe — `name` is the path identifier for views. Renames are
+          // forced to a replacement by `diff` above, so the cached
+          // `output.id` (set to `news.name` on first create) and the
+          // current `news.name` always agree by the time we land here.
+          const viewId = output?.id ?? news.name;
+          const observed = yield* get({ id: viewId }).pipe(
+            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+          );
+
+          // Ensure — POST creates the view under `news.name`.
+          if (observed === undefined) {
+            const result = yield* create(news);
+            return { ...result, id: news.name };
+          }
+
+          // Sync — the view exists; PUT against its id with the desired
+          // props.
+          const result = yield* update({ ...news, id: viewId });
+          return { ...result, id: viewId };
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* del({ id: output.id }).pipe(Effect.catchTag("NotFound", () => Effect.void));
+        }),
+        read: Effect.fn(function* ({ output }) {
+          if (!output?.id) return undefined;
+          return yield* get({ id: output.id }).pipe(
+            Effect.map((current) => ({ ...current, id: output.id })),
+            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+          );
+        }),
+      };
+    }),
+  );

package/src/VirtualField.ts

@@ -0,0 +1,123 @@
+import * as Axiom from "@distilled.cloud/axiom";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import type { Providers } from "./Providers.ts";
+
+export type VirtualFieldProps = Axiom.CreateVirtualFieldRequest;
+
+export type VirtualField = Resource<
+  "Axiom.VirtualField",
+  VirtualFieldProps,
+  Axiom.CreateVirtualFieldResponse,
+  never,
+  Providers
+>;
+
+/**
+ * An Axiom virtual field — a saved APL expression that appears as a derived
+ * column on a dataset at query time. Use these to standardise common
+ * computations (status classes, latency buckets, parsed JSON paths) so
+ * dashboards and monitors don't have to redefine them.
+ *
+ * Bound to a single `dataset`; changing the dataset triggers a replacement.
+ * @see https://axiom.co/docs/query-data/virtual-fields
+ *
+ * ### Creating a Virtual Field
+ * **Example:** HTTP status class (e.g. 200 → "2xx")
+ * ```typescript
+ * yield* Axiom.VirtualField("status-class", {
+ *   dataset: "my-app-traces",
+ *   name: "status_class",
+ *   description: "HTTP response class bucket",
+ *   expression: 'strcat(tostring(toint(status / 100)), "xx")',
+ *   type: "string",
+ * });
+ * ```
+ *
+ * **Example:** Latency bucket in seconds
+ * ```typescript
+ * yield* Axiom.VirtualField("latency-bucket", {
+ *   dataset: "my-app-traces",
+ *   name: "latency_bucket_s",
+ *   expression: "bin(duration_ms / 1000.0, 0.5)",
+ *   type: "number",
+ *   unit: "s",
+ * });
+ * ```
+ *
+ * @resource
+ * @product Dataset
+ */
+export const VirtualField = Resource<VirtualField>("Axiom.VirtualField");
+
+export const VirtualFieldProvider = () =>
+  Provider.effect(
+    VirtualField,
+    Effect.gen(function* () {
+      const create = yield* Axiom.createVirtualField;
+      const update = yield* Axiom.updateVirtualField;
+      const get = yield* Axiom.getVirtualField;
+      const del = yield* Axiom.deleteVirtualField;
+      const listVirtualFields = yield* Axiom.getVirtualFields;
+      const listDatasets = yield* Axiom.getDatasets;
+
+      return {
+        stables: ["id"],
+        // Axiom only exposes a per-dataset virtual-field enumeration
+        // (`GET /v2/vfields?dataset=...`); there is no account-wide list. So
+        // enumerate every dataset (`GET /v2/datasets`), fan out the per-dataset
+        // vfields list with bounded concurrency, and flatten. Each row already
+        // matches the `read` Attributes shape (`CreateVirtualFieldOutput`), so
+        // it's directly usable by `delete` with no follow-up read.
+        list: () =>
+          Effect.gen(function* () {
+            const datasets = yield* listDatasets({});
+            const perDataset = yield* Effect.forEach(
+              datasets,
+              (ds) => listVirtualFields({ dataset: ds.name }),
+              { concurrency: 10 },
+            );
+            return perDataset.flat().map((vf) => ({ ...vf }));
+          }),
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          if (output && news.dataset !== output.dataset) {
+            return { action: "replace" } as const;
+          }
+          return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ news, output }) {
+          // Observe — Axiom assigns the virtual-field id server-side, so
+          // the only handle to a previously-created field is the cached
+          // `output.id`. Probe for live state with that id; treat NotFound
+          // (deleted out-of-band) as "no observed state" so we converge by
+          // re-creating.
+          const observed = output?.id
+            ? yield* get({ id: output.id }).pipe(
+                Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+              )
+            : undefined;
+
+          // Ensure — POST mints a new virtual field with a fresh id.
+          if (observed === undefined) {
+            return yield* create(news);
+          }
+
+          // Sync — the field exists; PUT against its id with the desired
+          // props. `dataset` is replacement-only (handled in diff).
+          return yield* update({ ...news, id: observed.id });
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* del({ id: output.id }).pipe(Effect.catchTag("NotFound", () => Effect.void));
+        }),
+        read: Effect.fn(function* ({ output }) {
+          if (!output?.id) return undefined;
+          return yield* get({ id: output.id }).pipe(
+            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+          );
+        }),
+      };
+    }),
+  );

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from "./Annotation.ts";
+export * from "./ApiToken.ts";
+export * from "./AuthProvider.ts";
+export * from "./Chart.ts";
+export * from "./Credentials.ts";
+export * from "./Dashboard.ts";
+export * from "./Dataset.ts";
+export * from "./Monitor.ts";
+export * from "./Notifier.ts";
+export * from "./Telemetry.ts";
+export * from "./Providers.ts";
+export * from "./View.ts";
+export * from "./VirtualField.ts";