@dbx-tools/appkit-mastra 0.1.13 → 0.1.14

package/src/observability.ts

@@ -1,92 +1,144 @@
 /**
- * Mastra observability wiring for the `@dbx-tools/appkit-phoenix`
- * sibling plugin.
+ * Mastra observability wired through the same OTel pipeline AppKit's
+ * built-in plugins (e.g. `agents`) use, via `@mastra/otel-bridge`.
  *
- * Mastra's `Observability` registry accepts any
- * `@mastra/observability` `BaseExporter`. We use `OtelExporter` from
- * `@mastra/otel-exporter` (Mastra's first-party OTLP shim) with the
- * `custom` provider pointed at Phoenix's local collector URL. No
- * Arize-specific wrapper is needed - Phoenix is a vanilla
- * OpenInference-compatible OTLP/HTTP receiver.
+ * How traces flow:
  *
- * Discovery is structural so this module doesn't depend on
- * `@dbx-tools/appkit-phoenix` at compile time: we look up the
- * registered plugin by its registered name (`"phoenix"`) and read its
- * `exports().collectorEndpoint()` if it is shaped like the phoenix
- * plugin. The phoenix package is therefore an *optional* sibling -
- * apps that don't install it just get an undefined observability
- * config and Mastra runs without OTLP export.
+ * 1. `@databricks/appkit` boots a global `NodeSDK` in
+ *    `TelemetryManager.initialize()` (during `createApp`) when
+ *    `OTEL_EXPORTER_OTLP_ENDPOINT` is set in the process env.
+ * 2. Every AppKit plugin span (e.g. the `agents` plugin's
+ *    `executeStream`) is created via the global OTel tracer
+ *    (`trace.getTracer(<plugin>)`), so it lands on that NodeSDK and
+ *    is shipped through its OTLP exporter.
+ * 3. The Mastra `OtelBridge` ALSO creates real OTel spans on the same
+ *    global tracer for every Mastra operation (agent runs, model
+ *    calls, tool invocations, workflow steps). They inherit the
+ *    ambient OTel context, so when Mastra is invoked from inside an
+ *    AppKit HTTP span the trace stays connected.
+ *
+ * Net effect: Mastra spans get exactly the treatment AppKit's
+ * `agents` plugin gets. No custom OTLP pipeline lives in this
+ * package; the OTLP endpoint, headers, and resource attributes are
+ * driven by the standard OTel env vars
+ * (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`,
+ * `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`, ...) and consumed
+ * by AppKit's `TelemetryManager`. Set those once and both AppKit and
+ * Mastra spans end up at the same backend.
+ *
+ * When `OTEL_EXPORTER_OTLP_ENDPOINT` is unset the bridge is not
+ * registered at all (unless `observability: true` forces it on), so
+ * Mastra does not emit `[OtelBridge] No OTEL span found` warnings.
  */
 
-import type { pluginUtils } from "@dbx-tools/appkit-shared";
 import { Observability } from "@mastra/observability";
-import { OtelExporter } from "@mastra/otel-exporter";
+import { OtelBridge } from "@mastra/otel-bridge";
+
+import { TRACE_REQUEST_CONTEXT_KEYS } from "./config";
+import { log } from "@dbx-tools/shared-core";
+import { project } from "@dbx-tools/core";
 
-/** Plugin name the phoenix plugin registers under (matches `phoenix()`). */
-const PHOENIX_PLUGIN_NAME = "phoenix";
+const logger = log.logger("mastra/observability");
 
-/** Structural shape of the bits of `phoenix().exports()` we touch. */
-interface PhoenixExportsLike {
-  collectorEndpoint?(): string | undefined;
+const DEFAULT_SERVICE_NAME = "mastra";
+
+export interface BuildObservabilityOptions {
+  /**
+   * Whether to wire the Mastra `OtelBridge`. Mirrors
+   * {@link MastraPluginConfig.observability}:
+   *
+   * - `undefined` (auto): on only when `OTEL_EXPORTER_OTLP_ENDPOINT` or
+   *   `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` is set (same signal AppKit's
+   *   `TelemetryManager` uses to register a real tracer). When unset,
+   *   skip the bridge entirely so Mastra does not emit
+   *   `[OtelBridge] No OTEL span found` warnings on the noop tracer.
+   * - `true`: force on even without an OTLP endpoint.
+   * - `false`: force off.
+   */
+  enabled?: boolean;
+  /**
+   * Service name attached to the Mastra `Observability` config. Used
+   * as the tracer scope name on bridged OTel spans (the `service.name`
+   * resource attribute is owned by AppKit's `TelemetryManager` instead
+   * - it reads `OTEL_SERVICE_NAME` / `DATABRICKS_APP_NAME` at
+   * `createApp` time).
+   *
+   * Defaults to project name then `"mastra"`.
+   */
+  serviceName?: string;
+  /**
+   * `RequestContext` keys to extract as span metadata on every Mastra
+   * trace. Defaults to {@link TRACE_REQUEST_CONTEXT_KEYS} (user id,
+   * thread id, request id, environment, model override, ...).
+   *
+   * Supports dot notation for nested values per the Mastra docs.
+   */
+  requestContextKeys?: readonly string[];
 }
 
-/** Structural shape of an AppKit plugin instance with `exports()`. */
-interface PluginWithExports {
-  exports?(): unknown;
+/** True when AppKit's global OTel pipeline is configured to export traces. */
+export function isOtlpTracingConfigured(): boolean {
+  return Boolean(
+    process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
+  );
 }
 
 /**
- * If the sibling `phoenix` plugin is registered AND has booted with a
- * usable collector URL, return a Mastra `Observability` configured to
- * stream traces + logs there. Otherwise return `undefined` so the
- * caller can omit the field on the `new Mastra({...})` constructor.
+ * Build a Mastra `Observability` whose spans ride AppKit's global
+ * OTel pipeline via `@mastra/otel-bridge`.
  *
- * The exporter uses `provider.custom` with `http/protobuf`, which is
- * what Phoenix's `/v1/traces` endpoint speaks natively. Switching
- * Phoenix to gRPC would be a one-line `protocol: "grpc"` change and
- * a different exported URL.
+ * Returns `undefined` when tracing is off: either the caller passed
+ * `enabled: false`, or auto mode finds no OTLP endpoint (the default).
+ * Skipping the bridge in that case avoids `[OtelBridge] No OTEL span
+ * found` log spam from Mastra spans that have no parent on the noop
+ * tracer.
  */
-export function buildPhoenixObservability(
-  context: pluginUtils.PluginContextLike | undefined,
-  serviceName: string,
-): Observability | undefined {
-  const endpoint = readPhoenixEndpoint(context);
-  if (!endpoint) return undefined;
+export async function buildObservability(
+  options?: BuildObservabilityOptions,
+): Promise<Observability | undefined> {
+  const otelBase = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+  const otelTracesOverride = process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT;
+  const otlpConfigured = isOtlpTracingConfigured();
+
+  if (options?.enabled === false || (options?.enabled !== true && !otlpConfigured)) {
+    logger.info("Mastra observability off", {
+      reason:
+        options?.enabled === false
+          ? "disabled in plugin config"
+          : "OTEL_EXPORTER_OTLP_ENDPOINT unset",
+    });
+    return undefined;
+  }
+
+  const serviceName = options?.serviceName ?? (await project.name()) ?? DEFAULT_SERVICE_NAME;
+  const requestContextKeys = [...(options?.requestContextKeys ?? TRACE_REQUEST_CONTEXT_KEYS)];
+
+  // The OTel HTTP exporter treats `OTEL_EXPORTER_OTLP_ENDPOINT` as a
+  // *base* URL and appends the signal path itself (e.g.
+  // `http://localhost:6006` -> `http://localhost:6006/v1/traces`). Log
+  // the resolved POST URL so misconfigurations (e.g. accidentally
+  // setting the base var to a `/v1/traces`-suffixed URL, which makes
+  // the SDK POST to `.../v1/traces/v1/traces` and Phoenix 404s) are
+  // obvious in startup output.
+  const resolvedTracesUrl = otelTracesOverride
+    ? otelTracesOverride
+    : otelBase
+      ? `${otelBase.replace(/\/+$/, "")}/v1/traces`
+      : undefined;
+  logger.info("Mastra observability wired through OTel bridge", {
+    serviceName,
+    requestContextKeys,
+    otelBase: otelBase ?? "<unset>",
+    resolvedTracesUrl: resolvedTracesUrl ?? "<unset>",
+  });
 
   return new Observability({
     configs: {
-      phoenix: {
+      serviceName: {
         serviceName,
-        exporters: [
-          new OtelExporter({
-            provider: {
-              custom: {
-                endpoint,
-                protocol: "http/protobuf",
-              },
-            },
-          }),
-        ],
+        bridge: new OtelBridge(),
+        requestContextKeys,
       },
     },
   });
 }
-
-/**
- * Pull the OTLP collector URL out of the registered `phoenix` plugin.
- * Tolerant of the plugin being absent (returns `undefined`) and of a
- * future shape change in its exports (anything that's not a string
- * is ignored). The lookup is keyed off the registered plugin *name*
- * so this file does not depend on `@dbx-tools/appkit-phoenix`.
- */
-function readPhoenixEndpoint(
-  context: pluginUtils.PluginContextLike | undefined,
-): string | undefined {
-  if (!context) return undefined;
-  const plugin = context.getPlugins().get(PHOENIX_PLUGIN_NAME) as
-    | PluginWithExports
-    | undefined;
-  const exports_ = plugin?.exports?.() as PhoenixExportsLike | undefined;
-  const url = exports_?.collectorEndpoint?.();
-  return typeof url === "string" ? url : undefined;
-}

package/src/pagination.ts

@@ -0,0 +1,34 @@
+/**
+ * Query-parameter coercion shared by the paginated custom routes
+ * (`history` / `threads`). Each route keeps its own page-size default
+ * and hard cap and passes them in, so the coercion rules stay in one
+ * place without collapsing the routes' distinct sizing.
+ */
+
+/** Bounds for {@link clampPerPage}. */
+export interface PerPageBounds {
+  /** Page size used for empty / non-positive / non-numeric inputs. */
+  fallback: number;
+  /** Hard cap so a misbehaving client can't fetch everything at once. */
+  max: number;
+}
+
+/** Coerce / clamp a `perPage` value, falling back to `bounds.fallback`. */
+export function clampPerPage(value: number | undefined, bounds: PerPageBounds): number {
+  if (value === undefined || Number.isNaN(value)) return bounds.fallback;
+  const n = Math.trunc(value);
+  if (n <= 0) return bounds.fallback;
+  return Math.min(n, bounds.max);
+}
+
+/**
+ * Coerce a Hono query value into a non-negative integer. Returns
+ * `undefined` for empty / non-numeric / negative inputs so the caller
+ * can apply its built-in defaults.
+ */
+export function parseIntParam(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) return undefined;
+  return Math.trunc(n);
+}