@qlever-llc/trellis 0.8.4 → 0.9.0-rc.10

package/src/telemetry/core.ts

@@ -0,0 +1,31 @@
+import {
+  type Context,
+  context,
+  type Span,
+  SpanKind,
+  SpanStatusCode,
+  trace,
+  type Tracer,
+} from "@opentelemetry/api";
+
+export function getTracer(scope = "@qlever-llc/trellis/tracing"): Tracer {
+  return trace.getTracer(scope);
+}
+
+export function getActiveSpan(): Span | undefined {
+  return trace.getActiveSpan();
+}
+
+export function withSpan<T>(span: Span, fn: () => T): T {
+  return context.with(trace.setSpan(context.active(), span), fn);
+}
+
+export async function withSpanAsync<T>(
+  span: Span,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return context.with(trace.setSpan(context.active(), span), fn);
+}
+
+export { context, SpanKind, SpanStatusCode, trace };
+export type { Context, Span };

package/src/telemetry/env.ts

@@ -0,0 +1,23 @@
+import * as dntShim from "../_dnt.shims.js";
+type DenoLike = {
+  env?: {
+    get(key: string): string | undefined;
+  };
+};
+
+type ProcessLike = {
+  env?: Record<string, string | undefined>;
+};
+
+// Shared telemetry code needs environment access without assuming Deno or Node.
+export function getEnv(key: string): string | undefined {
+  const deno = dntShim.dntGlobalThis as typeof dntShim.dntGlobalThis & { Deno?: DenoLike };
+  if (deno.Deno?.env?.get) {
+    return deno.Deno.env.get(key);
+  }
+
+  const processGlobal = dntShim.dntGlobalThis as typeof dntShim.dntGlobalThis & {
+    process?: ProcessLike;
+  };
+  return processGlobal.process?.env?.[key];
+}

package/src/telemetry/mod.ts

@@ -0,0 +1,26 @@
+export type { HeaderCarrier } from "./carrier.js";
+export {
+  createMapCarrier,
+  extractTraceContext,
+  injectTraceContext,
+} from "./carrier.js";
+export type { Context, Span } from "./core.js";
+export {
+  context,
+  getActiveSpan,
+  getTracer,
+  SpanKind,
+  SpanStatusCode,
+  trace,
+  withSpan,
+  withSpanAsync,
+} from "./core.js";
+export { getEnv } from "./env.js";
+export type { NatsHeadersLike } from "./nats.js";
+export { createNatsHeaderCarrier } from "./nats.js";
+export { configureErrorTraceId } from "./result.js";
+export {
+  getTrellisTracer,
+  startClientSpan,
+  startServerSpan,
+} from "./trellis.js";

package/src/telemetry/nats.ts

@@ -0,0 +1,15 @@
+import type { HeaderCarrier } from "./carrier.js";
+
+export interface NatsHeadersLike {
+  get(key: string): string | undefined;
+  set(key: string, value: string): void;
+}
+
+export function createNatsHeaderCarrier(
+  headers: NatsHeadersLike,
+): HeaderCarrier {
+  return {
+    get: (key: string) => headers.get(key),
+    set: (key: string, value: string) => headers.set(key, value),
+  };
+}

package/src/telemetry/result.ts

@@ -0,0 +1,20 @@
+import { trace } from "@opentelemetry/api";
+import { BaseError } from "@qlever-llc/result";
+
+let traceIdGetterConfigured = false;
+
+export function configureErrorTraceId(): void {
+  if (traceIdGetterConfigured) return;
+  traceIdGetterConfigured = true;
+
+  BaseError.traceIdGetter = () => {
+    const span = trace.getActiveSpan();
+    if (!span) return undefined;
+
+    const spanContext = span.spanContext();
+    if (spanContext.traceId === "00000000000000000000000000000000") {
+      return undefined;
+    }
+    return spanContext.traceId;
+  };
+}

package/src/telemetry/trace.ts

@@ -0,0 +1,39 @@
+import type { Context, Span } from "@opentelemetry/api";
+import { SpanKind } from "@opentelemetry/api";
+import { getTracer } from "./core.js";
+
+const TRELLIS_INSTRUMENTATION_SCOPE = "@qlever-llc/trellis";
+
+export function getTrellisTracer() {
+  return getTracer(TRELLIS_INSTRUMENTATION_SCOPE);
+}
+
+export function startClientSpan(method: string, subject: string): Span {
+  return getTrellisTracer().startSpan(`rpc.client.${method}`, {
+    kind: SpanKind.CLIENT,
+    attributes: {
+      "rpc.system": "nats",
+      "rpc.method": method,
+      "messaging.destination": subject,
+    },
+  });
+}
+
+export function startServerSpan(
+  method: string,
+  subject: string,
+  parentContext?: Context,
+): Span {
+  return getTrellisTracer().startSpan(
+    `rpc.server.${method}`,
+    {
+      kind: SpanKind.SERVER,
+      attributes: {
+        "rpc.system": "nats",
+        "rpc.method": method,
+        "messaging.destination": subject,
+      },
+    },
+    parentContext,
+  );
+}

package/src/telemetry/trellis.ts

@@ -0,0 +1 @@
+export { getTrellisTracer, startClientSpan, startServerSpan } from "./trace.js";

package/src/tracing.ts

@@ -0,0 +1,28 @@
+// Keep this subpath for Trellis-specific tracing convenience without exposing
+// telemetry from the root `@qlever-llc/trellis` package surface.
+import "./_dnt.polyfills.js";
+
+export type { HeaderCarrier, NatsHeadersLike } from "./telemetry/mod.js";
+export {
+  configureErrorTraceId,
+  context,
+  createMapCarrier,
+  createNatsHeaderCarrier,
+  extractTraceContext,
+  getActiveSpan,
+  getTrellisTracer as getTracer,
+  injectTraceContext,
+  SpanKind,
+  SpanStatusCode,
+  startClientSpan,
+  startServerSpan,
+  trace,
+  withSpan,
+  withSpanAsync,
+} from "./telemetry/mod.js";
+export function initTracing(serviceName: string): void {
+  const load = new Function("specifier", "return import(specifier);") as (
+    specifier: string,
+  ) => Promise<{ initTracing(serviceName: string): void }>;
+  void load("./telemetry/init.ts").then((mod) => mod.initTracing(serviceName));
+}