feat(cli): Add a CLI to build deep-links to Central ELK

.github/workflows/ci.yaml

@@ -11,6 +11,18 @@ on:
       - main
 
 jobs:
+  cli:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: denoland/setup-deno@v1
+        with:
+          deno-version: v1.x
+      - name: lint + compile
+        working-directory: cli
+        run: |
+          deno fmt --check
+          deno task compile
   test:
     runs-on: ubuntu-latest
     steps:

.github/workflows/release-cli.yml

@@ -0,0 +1,32 @@
+name: Release CLI
+
+on:
+  push:
+    tags:
+      - cli-v*
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: denoland/setup-deno@v1
+        with:
+          deno-version: v1.x
+      - name: lint + compile
+        working-directory: cli
+        run: |
+          deno fmt --check
+          deno task compile
+      - name: release
+        working-directory: cli/dist
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          sha256sum devx-logs > checksum.txt
+          gh release create ${{ github.ref }} * --generate-notes

.gitignore

@@ -0,0 +1 @@
+dist

cli/README.md

@@ -0,0 +1,61 @@
+# DevX Logs CLI
+
+A small tool to deep-link to Central ELK.
+
+## Installation via homebrew
+
+```bash
+brew tap guardian/homebrew-devtools
+brew install guardian/devtools/devx-logs
+
+# update
+brew upgrade devx-logs
+```
+
+## Usage
+
+- Open the logs for Riff-Raff in PROD
+  ```bash
+  devx-logs --space devx --stage PROD --app riff-raff
+  ```
+- Display the URL for logs from Riff-Raff in PROD
+  ```bash
+  devx-logs --space devx --stage PROD --app riff-raff --no-follow
+  ```
+- Open the logs for Riff-Raff in PROD, where the level is INFO, and show the
+  message and logger_name columns
+  ```bash
+  devx-logs --space devx --stage PROD --app riff-raff --filter level=INFO --filter region=eu-west-1 --column message --column logger_name
+  ```
+- Open the logs for the repository 'guardian/prism':
+  ```bash
+  devx-logs --filter gu:repo.keyword=guardian/prism --column message --column gu:repo
+  ```
+
+See all options via the `--help` flag:
+
+```bash
+devx-logs --help
+```
+
+## Releasing
+
+Releasing is semi-automated. To release a new version, create a new tag with the
+`cli-v` prefix:
+
+```bash
+git tag cli-v0.0.1
+```
+
+And then push the tag:
+
+```bash
+git push --tags
+```
+
+This will trigger [a GitHub Action](../.github/workflows/release-cli.yml),
+publishing a new version to GitHub releases.
+
+Once a new release is available, update the
+[Homebrew formula](https://github.com/guardian/homebrew-devtools/blob/main/Formula/devx-logs.rb)
+to point to the new version.

cli/deno.json

@@ -0,0 +1,6 @@
+{
+  "tasks": {
+    "compile": "deno compile --allow-run=open --target aarch64-apple-darwin --output dist/devx-logs index.ts",
+    "demo": "deno run --allow-run=open index.ts --space devx --stack deploy --stage PROD --app riff-raff"
+  }
+}

cli/index.ts

@@ -0,0 +1,126 @@
+import type { Args } from "https://deno.land/[email protected]/flags/mod.ts";
+import { parse } from "https://deno.land/[email protected]/flags/mod.ts";
+import { open } from "https://deno.land/x/[email protected]/index.ts";
+
+export function getLink(
+  space: string,
+  filters: Record<string, string>,
+  columns: string[],
+): string {
+  const kibanaFilters = Object.entries(filters).map(([key, value]) => {
+    return `(query:(match_phrase:(${key}:'${value}')))`;
+  });
+
+  // The `#/` at the end is important for Kibana to correctly parse the query string
+  // The `URL` object moves this to the end of the string, which breaks the link.
+  const base = `https://logs.gutools.co.uk/s/${space}/app/discover#/`;
+
+  const query = {
+    ...(kibanaFilters.length > 0 && {
+      _g: `(filters:!(${kibanaFilters.join(",")}))`,
+    }),
+    ...(columns.length > 0 && {
+      _a: `(columns:!(${columns.join(",")}))`,
+    }),
+  };
+
+  const queryString = Object.entries(query)
+    .map(([key, value]) => `${key}=${value}`)
+    .join("&");
+
+  return `${base}?${queryString}`;
+}
+
+function parseArguments(args: string[]): Args {
+  return parse(args, {
+    boolean: ["follow"],
+    negatable: ["follow"],
+    string: ["space", "stack", "stage", "app"],
+    collect: ["column", "filter"],
+    stopEarly: false,
+    "--": true,
+    default: {
+      follow: true,
+      column: ["message"],
+      space: "default",
+      filter: [],
+    },
+  });
+}
+
+function escapeColon(str: string): string {
+  return str.includes(":") ? `'${str}'` : str;
+}
+
+function parseFilters(filter: string[]): Record<string, string> {
+  return filter.reduce((acc, curr) => {
+    const [key, value] = curr.split("=");
+    return { ...acc, [escapeColon(key)]: value };
+  }, {});
+}
+
+function removeUndefined(
+  obj: Record<string, string | undefined>,
+): Record<string, string> {
+  return Object.entries(obj).filter(([, value]) => !!value).reduce(
+    (acc, [key, value]) => ({
+      ...acc,
+      [key]: value,
+    }),
+    {},
+  );
+}
+
+function printHelp(): void {
+  console.log(`Usage: devx-logs [OPTIONS...]`);
+  console.log("\nOptional flags:");
+  console.log("  --help              Display this help and exit");
+  console.log("  --space             The Kibana space to use");
+  console.log("  --stack             The stack tag to filter by");
+  console.log("  --stage             The stage tag to filter by");
+  console.log("  --app               The app tag to filter by");
+  console.log(
+    "  --column            Which columns to display. Multiple: true. Default: 'message'",
+  );
+  console.log(
+    "  --filter            Additional filters to apply. Multiple: true. Format: key=value",
+  );
+  console.log("  --no-follow         Don't open the link in the browser");
+  console.log("\nExample:");
+  console.log(
+    "  devx-logs --space devx --stack deploy --stage PROD --app riff-raff",
+  );
+  console.log("\nAdvanced example:");
+  console.log(
+    "  devx-logs --space devx --stack deploy --stage PROD --app riff-raff --filter level=INFO --filter region=eu-west-1 --column message --column logger_name",
+  );
+}
+
+async function main(inputArgs: string[]) {
+  const args = parseArguments(inputArgs);
+
+  if (args.help) {
+    printHelp();
+    Deno.exit(0);
+  }
+
+  const { space, stack, stage, app, column, filter, follow } = args;
+
+  const mergedFilters: Record<string, string | undefined> = {
+    ...parseFilters(filter),
+    "stack.keyword": stack,
+    "stage.keyword": stage,
+    "app.keyword": app,
+  };
+
+  const filters = removeUndefined(mergedFilters);
+  const link = getLink(space, filters, column.map(escapeColon));
+
+  console.log(link);
+
+  if (follow) {
+    await open(link);
+  }
+}
+
+await main(Deno.args);