@synnaxlabs/alamos 0.1.0

package/src/log.ts

@@ -0,0 +1,104 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { type UnknownRecord } from "@synnaxlabs/x";
+
+import { Meta } from "@/meta";
+
+export const LOG_LEVELS = ["debug", "info", "warn", "error"] as const;
+export type LogLevel = (typeof LOG_LEVELS)[number];
+
+export interface LogLevelFilterProps {
+  key: string;
+  path: string;
+  level: LogLevel;
+}
+
+/**
+ * LogLevelFilter is a function that returns true if the log at the given
+ * level should be emitted.
+ */
+export type LogLevelFilter = (props: LogLevelFilterProps) => boolean;
+
+export const logThresholdFilter = (thresh: LogLevel): LogLevelFilter => {
+  const threshIdx = LOG_LEVELS.indexOf(thresh);
+  return ({ level }) => LOG_LEVELS.indexOf(level) >= threshIdx;
+};
+
+export interface LogLevelKeyFilterProps {
+  include?: string[];
+  exclude?: string[];
+}
+export const logLevelKeyFiler = (props: LogLevelKeyFilterProps): LogLevelFilter => {
+  const { include, exclude } = props;
+  return ({ key }) => {
+    if (include != null && !include.includes(key)) return false;
+    if (exclude != null && exclude.includes(key)) return false;
+    return true;
+  };
+};
+
+export interface LoggerProps {
+  filters?: LogLevelFilter[];
+}
+
+export class Logger {
+  meta: Meta = Meta.NOOP;
+  filters: LogLevelFilter[];
+
+  constructor(p: LoggerProps = {}) {
+    const { filters = [] } = p;
+    this.filters = filters;
+  }
+
+  private filter(level: LogLevel): boolean {
+    return (
+      !this.meta.noop &&
+      this.filters.every((f) =>
+        f({
+          key: this.meta.key,
+          path: this.meta.path,
+          level,
+        }),
+      )
+    );
+  }
+
+  child(meta: Meta): Logger {
+    const l = new Logger({ filters: this.filters });
+    l.meta = meta;
+    return l;
+  }
+
+  debug(msg: string, kv?: UnknownRecord): void {
+    if (!this.filter("debug")) return;
+    if (kv == null) console.log("%cDEBUG", "color: #8c00f0;", this.meta.path, msg);
+    else console.log("%cDEBUG", "color: #8c00f0;", this.meta.path, msg, kv);
+  }
+
+  info(msg: string, kv?: UnknownRecord): void {
+    if (!this.filter("info")) return;
+    if (kv == null) console.log("%cINFO", "color: #005eff;", this.meta.path, msg);
+    else console.log("%cINFO", "color: #005eff;", this.meta.path, msg, kv);
+  }
+
+  warn(msg: string, kv?: UnknownRecord): void {
+    if (!this.filter("warn")) return;
+    if (kv == null) console.warn("WARN", this.meta.path, msg);
+    else console.warn("WARN", this.meta.path, msg, kv);
+  }
+
+  error(msg: string, kv?: UnknownRecord): void {
+    if (!this.filter("error")) return;
+    if (kv == null) console.error("ERROR", this.meta.path, msg);
+    else console.error("ERROR", this.meta.path, msg, kv);
+  }
+
+  static readonly NOOP = new Logger();
+}

package/src/meta.ts

@@ -0,0 +1,41 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+export class Meta {
+  private readonly _noop: boolean = false;
+  readonly key: string;
+  readonly path: string;
+  readonly serviceName: string;
+
+  constructor(
+    key: string,
+    path: string,
+    serviceName: string = "",
+    noop: boolean = false,
+  ) {
+    this.key = key;
+    this.path = path;
+    this.serviceName = serviceName;
+    this._noop = noop;
+  }
+
+  child(key: string): Meta {
+    return new Meta(key, this.extendPath(key), this.serviceName);
+  }
+
+  extendPath(key: string): string {
+    return `${this.path}.${key}`;
+  }
+
+  get noop(): boolean {
+    return this._noop;
+  }
+
+  static readonly NOOP = new Meta("", "", "");
+}

package/src/trace.spec.ts

@@ -0,0 +1,38 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { beforeAll, describe, expect, it } from "vitest";
+
+import { instrumentation } from "@/dev";
+import { Instrumentation } from "@/instrumentation";
+import { Tracer } from "@/trace";
+
+describe("Trace", () => {
+  let ins: Instrumentation;
+  beforeAll(() => {
+    ins = instrumentation();
+  });
+  describe("initialize", () => {
+    it("should correctly initialize a tracer", () => {
+      const t = new Tracer();
+      expect(t).toBeDefined();
+    });
+  });
+  describe("trace", () => {
+    it("should start a span with the given key", () => {
+      ins.T.prod("test", (span) => {
+        expect(span.key).toEqual("test");
+      });
+    });
+    it("should trace an async function correctly", async () => {
+      const result = await ins.T.prod("async-test", async () => "test");
+      expect(result).toEqual("test");
+    });
+  });
+});

package/src/trace.ts

@@ -0,0 +1,188 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import {
+  type Span as OtelSpan,
+  type Tracer as OtelTracer,
+  context,
+  SpanStatusCode,
+  propagation,
+  type AttributeValue,
+} from "@opentelemetry/api";
+
+import {
+  type Environment,
+  type EnvironmentFilter,
+  envThresholdFilter,
+} from "@/environment";
+import { Meta } from "@/meta";
+
+/** Carrier is an entitty that can carry trace metadata across process bounds */
+export type Carrier = Record<string, string>;
+
+/** Function that executes under the given span */
+export type SpanF = (span: Span) => unknown;
+
+/**
+ * Tracer wraps an opentelemetry tracer to provide an opinionated intreface
+ * for tracing within the Synnax stack.
+ */
+export class Tracer {
+  private meta: Meta = Meta.NOOP;
+  private readonly tracer: OtelTracer;
+  private readonly filter: EnvironmentFilter;
+
+  constructor(
+    tracer?: OtelTracer,
+    filter: EnvironmentFilter = envThresholdFilter("debug"),
+  ) {
+    this.tracer = tracer as OtelTracer;
+    this.filter = filter;
+  }
+
+  child(meta: Meta): Tracer {
+    const t = new Tracer(this.tracer, this.filter);
+    t.meta = meta;
+    return t;
+  }
+
+  /**
+   * Starts a new span in the debug environment. If a span already exists in the
+   * current context, it will be used as the parent span.
+   *
+   * @param key - The name of the span.
+   * @param f - The function to run under the span.
+   * @returns A span that tracks program execution. If the Tracer's environment
+   * rejects the 'debug' environment or the Tracer is noop, a NoopSpan is returned.
+   */
+  debug<F extends SpanF>(key: string, f: F): ReturnType<F> {
+    return this.trace(key, "debug", f);
+  }
+
+  /**
+   * Starts a new span in the bench environment. If a span already exists in the
+   * current context, it will be used as the parent span.
+   *
+   * @param key - The name of the span.
+   * @param f - The function to run under the span.
+   * @returns A span that tracks program execution. If the Tracer's environment
+   * rejects the 'bench' environment or the Tracer is noop, a NoopSpan is returned.
+   */
+  bench<F extends SpanF>(key: string, f: F): ReturnType<F> {
+    return this.trace(key, "bench", f);
+  }
+
+  /**
+   * Starts a new span in the prod environment. If a span already exists in the
+   * current context, it will be used as the parent span.
+   *
+   * @param key - The name of the span.
+   * @param f - The function to run under the span.
+   * @returns A span that tracks program execution. If the Tracer's environment
+   * rejects the 'prod' environment or the Tracer is noop, a NoopSpan is returned.
+   */
+  prod<F extends SpanF>(key: string, f: F): ReturnType<F> {
+    return this.trace(key, "prod", f);
+  }
+
+  /**
+   * Stars a new span with the given key and environment. If a span already
+   * exists in the current context, it will be used as the parent span.
+   *
+   * @param key - The name of the span.
+   * @param env - The environment to run the span under.
+   * @param f - The function to run under the span.
+   * @returns A span that tracks program execution. If the Tracer's environment
+   * rejects the provided span or the Tracer is noop, a NoopSpan is returned.
+   */
+  trace<F extends SpanF>(key: string, env: Environment, f: F): ReturnType<F> {
+    if (this.meta.noop || !this.filter(env))
+      return f(new NoopSpan(key)) as ReturnType<F>;
+    return this.tracer.startActiveSpan(key, (otelSpan) => {
+      const span = new _Span(key, otelSpan);
+      const result = f(span);
+      otelSpan.end();
+      return result as ReturnType<F>;
+    });
+  }
+
+  /**
+   * Injects metadata about the current trace into the provided carrier. This
+   * metadata can be paresed on teh other side of a network or IPC request to
+   * allow the trace to proapgate across services.
+   *
+   * @param carrier - The carrier to inject the metadata into.
+   */
+  propagate(carrier: Carrier): void {
+    if (this.meta.noop) return;
+    const ctx = context.active();
+    propagation.inject(ctx, carrier, {
+      set: (carrier, key, value) => {
+        carrier[key] = value;
+      },
+    });
+  }
+
+  /** Tracer implementation that does nothing */
+  static readonly NOOP = new Tracer();
+}
+
+/** A span in a trace that can be used to track function execution */
+export interface Span {
+  /**
+   * The key identifying the span. This is the name of the key
+   * passed into the tracing method combined with the path of the
+   * instrumentation that started the span. For example, take the
+   * instrumentation titled 'synnax' and call to trace with 'test.
+   * The span key would be 'synnax.test'.
+   */
+  key: string;
+  /**
+   * If the error is not null, records the error in the span and sets
+   * its status to error.
+   */
+  recordError: (error?: Error | null) => void;
+  /**
+   * Sets the given key-value pair as an attribute on the span.
+   */
+  set: (key: string, value: AttributeValue) => void;
+}
+
+export class _Span implements Span {
+  key: string;
+  private readonly otel: OtelSpan;
+
+  constructor(key: string, span: OtelSpan) {
+    this.key = key;
+    this.otel = span;
+  }
+
+  set(key: string, value: AttributeValue): void {
+    this.otel.setAttribute(key, value);
+  }
+
+  recordError(error?: Error | null): void {
+    if (error == null) return;
+    this.otel.recordException(error);
+    this.otel.setStatus({ code: SpanStatusCode.ERROR });
+  }
+}
+
+/** Span implementation that does nothing */
+export class NoopSpan implements Span {
+  key: string;
+
+  constructor(key: string) {
+    this.key = key;
+  }
+
+  set(key: string, value: AttributeValue): void {}
+
+  recordError(_?: Error | null): void {}
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@synnaxlabs/tsconfig/base.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "experimentalDecorators": true,
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src/**/*.ts"],
+}

package/tsconfig.vite.json

@@ -0,0 +1,4 @@
+{
+  "extends": "@synnaxlabs/tsconfig/vite.json",
+  "include": ["vite.config.ts"]
+}

package/vite.config.ts

@@ -0,0 +1,26 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import path from "path";
+import { defineConfig } from "vite";
+import { lib } from "@synnaxlabs/vite-plugin";
+
+export default defineConfig({
+  plugins: [lib({ name: "alamos" })],
+  build: {
+    sourcemap: true,
+    minify: false,
+    lib: {
+      entry: {
+        index: path.resolve(".", "src/index.ts"),
+        dev: path.resolve(".", "src/dev/index.ts"),
+      },
+    }
+  },
+});