Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

4.2 KB
Raw Blame
// Copyright 2026 The OpenSandbox Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

import { DEFAULT_USER_AGENT } from "../core/constants.js";
import type { ConnectionConfig } from "../config/connection.js";
import { createRedirectSafeFetch } from "../config/redirectFetch.js";

const DISABLE_METRICS_ENV = "OPENSANDBOX_DISABLE_METRICS";

export interface SandboxCreateMetricsPayload {
  eventType: "sandbox.create";
  sandboxId?: string;
  image?: string;
  createDurationMs: number;
  success: boolean;
}

function readEnv(name: string): string | undefined {
  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } })
    ?.process?.env;
  const v = env?.[name];
  return typeof v === "string" && v.length ? v : undefined;
}

function envMetricsDisabled(): boolean {
  return readEnv(DISABLE_METRICS_ENV)?.trim() === "1";
}

function metricsDisabled(connectionConfig: ConnectionConfig): boolean {
  return connectionConfig.disableMetrics || envMetricsDisabled();
}

/**
 * Best-effort fire-and-forget report of sandbox create latency.
 * Never throws and never awaits for callers.
 * SDK identity is conveyed via the User-Agent header.
 */
export function reportSandboxCreateMetric(
  connectionConfig: ConnectionConfig,
  opts: {
    sandboxId?: string;
    image?: string;
    createDurationMs: number;
    success: boolean;
  }
): void {
  if (metricsDisabled(connectionConfig)) {
    return;
  }

  // Telemetry is best-effort and MUST NOT surface any exception to the
  // caller. This function is also invoked from Sandbox.create's failure
  // path; any exception thrown here — payload/URL/headers construction, a
  // custom `fetch` that throws synchronously on an invalid URL, or
  // `JSON.stringify` failing on an unserializable value — would otherwise
  // replace the original create failure. Guard the whole body so every
  // telemetry failure is swallowed.
  try {
    const payload: SandboxCreateMetricsPayload = {
      eventType: "sandbox.create",
      createDurationMs: Math.max(0, Math.floor(opts.createDurationMs)),
      success: opts.success,
    };
    if (opts.sandboxId) {
      payload.sandboxId = opts.sandboxId;
    }
    if (opts.image) {
      payload.image = opts.image;
    }

    const baseUrl = connectionConfig.getBaseUrl();
    const url = `${baseUrl.replace(/\/$/, "")}/metrics/events`;
    const headers: Record<string, string> = {
      "Content-Type": "application/json",
      ...(connectionConfig.headers ?? {}),
    };
    if (
      connectionConfig.apiKey &&
      !Object.keys(headers).some((name) => name.toLowerCase() === "open-sandbox-api-key")
    ) {
      headers["OPEN-SANDBOX-API-KEY"] = connectionConfig.apiKey;
    }
    if (
      !headers["User-Agent"] &&
      !headers["user-agent"]
    ) {
      headers["User-Agent"] =
        connectionConfig.userAgent || DEFAULT_USER_AGENT;
    }

    // Report through the redirect-safe transport so the API key is never
    // replayed if the lifecycle endpoint redirects cross-origin.
    const fetchImpl = createRedirectSafeFetch(baseUrl, connectionConfig.fetch, {
      overallTimeoutMs: connectionConfig.requestTimeoutSeconds * 1000,
    });
    void fetchImpl(url, {
      method: "POST",
      headers,
      body: JSON.stringify(payload),
    })
      .then(async (res) => {
        // Drain body to allow connection reuse; ignore status.
        try {
          await res.arrayBuffer();
        } catch {
          // ignore
        }
      })
      .catch(() => {
        // Metrics must never affect create UX.
      });
  } catch {
    // Metrics must never affect create UX, including construction failures
    // such as an invalid base URL or a custom `fetch` that throws synchronously.
  }
}