sailfork / t3code-github / .repos/ alchemy-effect/ packages/ domain/ src/ Telemetry.ts

import * as Context from "effect/Context";
import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
import * as Metric from "effect/Metric";
import * as Option from "effect/Option";
import * as Redacted from "effect/Redacted";
import * as Schema from "effect/Schema";
import * as Tracer from "effect/Tracer";

/**
 * Span attributes a declaration adds for its values: a command's input, an
 * event, a rejection. Nothing from a payload is recorded unless you return
 * it here, and a `Redacted` value you return is recorded as `<redacted>`.
 */
export type Attributes<V> = (value: V) => Readonly<Record<string, unknown>>;

/**
 * How a hosted model records telemetry. Tuning, not meaning, so it lives on
 * the Layer: `Bank.layer(handlers, { telemetry: { views: false } })`.
 */
export interface Options {
  /**
   * Trace every view applying an event. Views apply every event they fold,
   * so this is the busiest span.
   * @default true
   */
  readonly views?: boolean;
}

/** @internal */
export interface Resolved {
  readonly views: boolean;
}

/** @internal */
export const resolve = (options: Options | undefined): Resolved => ({
  views: options?.views ?? true,
});

/** A span's identity, stored with what it caused so later work can continue or link to it. @internal */
export const TraceJson = Schema.Struct({
  traceId: Schema.String,
  spanId: Schema.String,
  sampled: Schema.Boolean,
});
export type TraceJson = typeof TraceJson.Type;

/** The current span, as JSON, if any. @internal */
export const currentTrace: Effect.Effect<TraceJson | undefined> = Effect.currentParentSpan.pipe(
  Effect.map((span): TraceJson => ({
    traceId: span.traceId,
    spanId: span.spanId,
    sampled: span.sampled,
  })),
  Effect.orElseSucceed(() => undefined),
);

/** A stored trace, as a parent or link target. @internal */
export const spanOf = (trace: TraceJson): Tracer.ExternalSpan =>
  Tracer.externalSpan({ traceId: trace.traceId, spanId: trace.spanId, sampled: trace.sampled });

/**
 * The flow work belongs to: the id of the first command in a chain of
 * commands, events and reactions. Policies and sagas provide it, so every
 * command they send carries it on.
 *
 * @internal
 */
export class Correlation extends Context.Service<Correlation, { readonly id: string }>()(
  "alchemy/Domain/Correlation",
) {}

/** The correlation id for a new command: the one it was caused by, else its own id. @internal */
export const correlationFor = (commandId: string): Effect.Effect<string> =>
  Effect.map(Effect.serviceOption(Correlation), (c) => (Option.isSome(c) ? c.value.id : commandId));

const MAX_STRING = 256;
const MAX_ITEMS = 20;
const MAX_DEPTH = 4;

/** Flatten a decoded value into span attributes. `Redacted` values never appear. */
const flatten = (out: Record<string, unknown>, key: string, value: unknown, depth: number) => {
  if (value === undefined) return;
  if (Redacted.isRedacted(value)) {
    out[key] = "<redacted>";
  } else if (value === null || typeof value === "boolean" || typeof value === "number") {
    out[key] = value;
  } else if (typeof value === "string") {
    out[key] = value.length > MAX_STRING ? `${value.slice(0, MAX_STRING)}…` : value;
  } else if (typeof value === "bigint") {
    out[key] = value.toString();
  } else if (DateTime.isDateTime(value)) {
    out[key] = DateTime.formatIso(value);
  } else if (value instanceof Date) {
    out[key] = value.toISOString();
  } else if (value instanceof Uint8Array) {
    out[key] = `<${value.byteLength} bytes>`;
  } else if (depth >= MAX_DEPTH) {
    out[key] = "<nested>";
  } else if (Array.isArray(value)) {
    out[`${key}.length`] = value.length;
    value.slice(0, MAX_ITEMS).forEach((item, i) => flatten(out, `${key}.${i}`, item, depth + 1));
  } else if (typeof value === "object") {
    for (const [field, inner] of Object.entries(value)) {
      if (field === "_tag") continue;
      flatten(out, `${key}.${field}`, inner, depth + 1);
    }
  }
};

/**
 * The attributes a declaration adds for one of its values, if it declares
 * `attributes`. Values are flattened, capped, and `Redacted` values hidden.
 *
 * @internal
 */
export const attributesOf = (cls: unknown, value: unknown): Record<string, unknown> => {
  const attributes = (cls as { readonly attributes?: Attributes<any> } | undefined)?.attributes;
  if (attributes === undefined) return {};
  const out: Record<string, unknown> = {};
  for (const [key, inner] of Object.entries(attributes(value))) flatten(out, key, inner, 0);
  return out;
};

// ---------------------------------------------------------------- metrics

const ms = Metric.exponentialBoundaries({ start: 1, factor: 2, count: 22 });

/** Commands handled, by `domain.aggregate`, `domain.command` and `domain.outcome`. */
export const commands = Metric.counter("domain.commands", {
  description: "Commands handled by aggregates",
  incremental: true,
});
/** How long an aggregate took to decide and commit a command, in milliseconds. */
export const commandDuration = Metric.histogram("domain.command.duration", {
  description: "Milliseconds to decide and commit a command",
  boundaries: ms,
});
/** Events committed, by `domain.aggregate` and `domain.event`. */
export const events = Metric.counter("domain.events", {
  description: "Events committed by aggregates",
  incremental: true,
});
/** Milliseconds from an event's commit to a reaction handling it, by `domain.consumer`. */
export const lag = Metric.histogram("domain.lag", {
  description: "Milliseconds from commit to handling, per consumer",
  boundaries: ms,
});
/** Reaction runs, by `domain.kind`, `domain.consumer` and `domain.outcome`. */
export const runs = Metric.counter("domain.runs", {
  description: "Policy, view, projection and saga runs",
  incremental: true,
});
/** Inputs per projection batch. */
export const batchSize = Metric.histogram("domain.projection.batch_size", {
  description: "Inputs per projection batch",
  boundaries: Metric.exponentialBoundaries({ start: 1, factor: 2, count: 12 }),
});
/** External system calls, by `domain.system`, `domain.operation` and `domain.outcome`. */
export const externalCalls = Metric.counter("domain.external.calls", {
  description: "Calls to external systems",
  incremental: true,
});

/** @internal */
export const record = <M extends Metric.Metric<number, any>>(
  metric: M,
  attributes: Record<string, string>,
  value = 1,
) => Metric.update(Metric.withAttributes(metric, attributes), value);

/** The outcome of an exit, for metrics and spans: ok, the failure's tag, or defect. @internal */
export const outcomeOf = (failure: unknown): string =>
  failure === undefined
    ? "ok"
    : typeof failure === "object" && failure !== null && "_tag" in failure
      ? String((failure as { readonly _tag: unknown })._tag)
      : "defect";