@juspay/neurolink 9.41.0 → 9.42.1

package/scripts/observability/import-openobserve-dashboard.mjs

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const defaultDashboardPath = path.resolve(
+  __dirname,
+  "../../docs/assets/dashboards/neurolink-proxy-observability-dashboard.json",
+);
+
+function usage() {
+  console.error(`Usage:
+  node scripts/observability/import-openobserve-dashboard.mjs [options]
+
+Options:
+  --dashboard <path>       Dashboard JSON to import
+  --openobserve-url <url>  OpenObserve base URL
+  --org <org>              OpenObserve org identifier
+  --user <email>           OpenObserve login email
+  --password <password>    OpenObserve login password
+  --replace-by-title       Delete older dashboards with the same title after import
+  --dry-run                Validate config and list matching dashboards without importing
+  --help                   Show this message
+`);
+}
+
+function parseArgs(argv) {
+  const options = {
+    dashboard: defaultDashboardPath,
+    openobserveUrl: process.env.NEUROLINK_OPENOBSERVE_URL ?? "http://localhost:5080",
+    org: process.env.NEUROLINK_OPENOBSERVE_ORG ?? "default",
+    user: process.env.NEUROLINK_OPENOBSERVE_USER ?? "root@example.com",
+    password:
+      process.env.NEUROLINK_OPENOBSERVE_PASSWORD ?? "Complexpass#123",
+    replaceByTitle: false,
+    dryRun: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    switch (arg) {
+      case "--dashboard":
+        options.dashboard = argv[index + 1];
+        index += 1;
+        break;
+      case "--openobserve-url":
+        options.openobserveUrl = argv[index + 1];
+        index += 1;
+        break;
+      case "--org":
+        options.org = argv[index + 1];
+        index += 1;
+        break;
+      case "--user":
+        options.user = argv[index + 1];
+        index += 1;
+        break;
+      case "--password":
+        options.password = argv[index + 1];
+        index += 1;
+        break;
+      case "--replace-by-title":
+        options.replaceByTitle = true;
+        break;
+      case "--dry-run":
+        options.dryRun = true;
+        break;
+      case "--help":
+        usage();
+        process.exit(0);
+        break; // satisfy noFallthroughSwitchClause
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+async function readDashboardTemplate(filePath) {
+  const raw = JSON.parse(await fs.readFile(filePath, "utf8"));
+  const template = structuredClone(raw.v5 ?? raw);
+
+  delete template.dashboardId;
+  delete template.owner;
+  delete template.created;
+
+  if (!template.title) {
+    throw new Error(`Dashboard template ${filePath} is missing v5.title`);
+  }
+
+  return template;
+}
+
+function normalizeDashboardList(payload) {
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+
+  if (Array.isArray(payload?.dashboards)) {
+    return payload.dashboards;
+  }
+
+  if (Array.isArray(payload?.data)) {
+    return payload.data;
+  }
+
+  return [];
+}
+
+function dashboardIdOf(item) {
+  return item?.dashboardId ?? item?.v5?.dashboardId ?? null;
+}
+
+function dashboardTitleOf(item) {
+  return item?.title ?? item?.v5?.title ?? null;
+}
+
+async function requestJson(url, { user, password, ...init }) {
+  const response = await fetch(url, {
+    ...init,
+    headers: {
+      Authorization: `Basic ${Buffer.from(`${user}:${password}`).toString("base64")}`,
+      "Content-Type": "application/json",
+      ...(init.headers ?? {}),
+    },
+  });
+
+  const text = await response.text();
+  let payload = null;
+
+  if (text) {
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      payload = text;
+    }
+  }
+
+  if (!response.ok) {
+    const detail =
+      typeof payload === "string" ? payload : JSON.stringify(payload, null, 2);
+    throw new Error(`${response.status} ${response.statusText}: ${detail}`);
+  }
+
+  return payload;
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const dashboard = await readDashboardTemplate(
+    path.resolve(process.cwd(), options.dashboard),
+  );
+  const baseUrl = options.openobserveUrl.replace(/\/+$/, "");
+  const dashboardsUrl = `${baseUrl}/api/${options.org}/dashboards`;
+
+  const existingPayload = await requestJson(dashboardsUrl, {
+    method: "GET",
+    user: options.user,
+    password: options.password,
+  });
+  const existingDashboards = normalizeDashboardList(existingPayload).filter(
+    (item) => dashboardTitleOf(item) === dashboard.title,
+  );
+
+  if (options.dryRun) {
+    console.log(
+      JSON.stringify(
+        {
+          dashboardPath: path.resolve(process.cwd(), options.dashboard),
+          title: dashboard.title,
+          matchingDashboardIds: existingDashboards
+            .map((item) => dashboardIdOf(item))
+            .filter(Boolean),
+          openobserveUrl: baseUrl,
+          org: options.org,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  const createdPayload = await requestJson(dashboardsUrl, {
+    method: "POST",
+    body: JSON.stringify(dashboard),
+    user: options.user,
+    password: options.password,
+  });
+
+  const createdDashboardId =
+    createdPayload?.dashboardId ??
+    createdPayload?.v5?.dashboardId ??
+    createdPayload?.data?.dashboardId;
+
+  if (!createdDashboardId) {
+    throw new Error("OpenObserve did not return a dashboardId for the new dashboard");
+  }
+
+  const deletedDashboardIds = [];
+
+  if (options.replaceByTitle) {
+    for (const entry of existingDashboards) {
+      const duplicateId = dashboardIdOf(entry);
+      if (!duplicateId || duplicateId === createdDashboardId) {
+        continue;
+      }
+
+      await requestJson(`${dashboardsUrl}/${duplicateId}`, {
+        method: "DELETE",
+        user: options.user,
+        password: options.password,
+      });
+      deletedDashboardIds.push(duplicateId);
+    }
+  }
+
+  console.log(
+    JSON.stringify(
+      {
+        title: dashboard.title,
+        dashboardId: createdDashboardId,
+        deletedDashboardIds,
+        openobserveUrl: `${baseUrl}/web/dashboards?org_identifier=${options.org}`,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/scripts/observability/manage-local-openobserve.sh

@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+COMPOSE_FILE="${SCRIPT_DIR}/docker-compose.proxy-observability.yaml"
+ENV_FILE="${SCRIPT_DIR}/proxy-observability.env"
+IMPORT_SCRIPT="${SCRIPT_DIR}/import-openobserve-dashboard.mjs"
+DOCTOR_SCRIPT="${SCRIPT_DIR}/check-proxy-telemetry.mjs"
+
+load_env() {
+  if [[ -f "${ENV_FILE}" ]]; then
+    while IFS= read -r line || [[ -n "${line}" ]]; do
+      [[ "${line}" =~ ^[[:space:]]*$ ]] && continue
+      [[ "${line}" =~ ^[[:space:]]*# ]] && continue
+
+      line="${line#"${line%%[![:space:]]*}"}"
+      if [[ "${line}" =~ ^[[:space:]]*export[[:space:]]+ ]]; then
+        line="${line#export }"
+      fi
+
+      if [[ "${line}" != *=* ]]; then
+        continue
+      fi
+
+      local key="${line%%=*}"
+      local value="${line#*=}"
+
+      key="${key#"${key%%[![:space:]]*}"}"
+      key="${key%"${key##*[![:space:]]}"}"
+      value="${value#"${value%%[![:space:]]*}"}"
+      value="${value%"${value##*[![:space:]]}"}"
+
+      if [[ "${value}" =~ ^\".*\"$ || "${value}" =~ ^\'.*\'$ ]]; then
+        value="${value:1:${#value}-2}"
+      fi
+
+      if [[ -n "${key}" ]]; then
+        if [[ ! "${key}" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
+          echo "Skipping invalid env var name in ${ENV_FILE}: ${key}" >&2
+          continue
+        fi
+        printf -v "${key}" '%s' "${value}"
+        export "${key}"
+      fi
+    done < "${ENV_FILE}"
+  fi
+}
+
+select_compose() {
+  if command -v docker >/dev/null 2>&1 && docker compose version >/dev/null 2>&1; then
+    COMPOSE_CMD=(docker compose)
+    return
+  fi
+
+  if command -v docker-compose >/dev/null 2>&1; then
+    COMPOSE_CMD=(docker-compose)
+    return
+  fi
+
+  if command -v podman-compose >/dev/null 2>&1; then
+    COMPOSE_CMD=(podman-compose)
+    return
+  fi
+
+  echo "No supported compose command found. Install docker compose, docker-compose, or podman-compose." >&2
+  exit 1
+}
+
+compose() {
+  "${COMPOSE_CMD[@]}" -p "${NEUROLINK_OBSERVABILITY_PROJECT_NAME}" -f "${COMPOSE_FILE}" "$@"
+}
+
+wait_for_http() {
+  local name="$1"
+  local url="$2"
+  local attempts="${3:-60}"
+
+  for ((attempt = 1; attempt <= attempts; attempt += 1)); do
+    if curl -fsS "${url}" >/dev/null 2>&1; then
+      return 0
+    fi
+    sleep 1
+  done
+
+  echo "${name} did not become healthy at ${url}" >&2
+  return 1
+}
+
+print_status() {
+  local openobserve_status="DOWN"
+  local collector_status="DOWN"
+
+  if curl -fsS "${NEUROLINK_OPENOBSERVE_URL}/healthz" >/dev/null 2>&1; then
+    openobserve_status="UP"
+  fi
+
+  if curl -fsS "http://localhost:${NEUROLINK_OTEL_HEALTH_PORT}/" >/dev/null 2>&1; then
+    collector_status="UP"
+  fi
+
+  cat <<EOF
+OpenObserve: ${openobserve_status}
+  UI: ${NEUROLINK_OPENOBSERVE_URL}
+  Login: ${NEUROLINK_OPENOBSERVE_USER}
+
+OTEL Collector: ${collector_status}
+  OTLP gRPC: http://localhost:${NEUROLINK_OTLP_GRPC_PORT}
+  OTLP HTTP: http://localhost:${NEUROLINK_OTLP_HTTP_PORT}
+  Health: http://localhost:${NEUROLINK_OTEL_HEALTH_PORT}
+EOF
+}
+
+print_usage() {
+  cat <<EOF
+Usage: bash scripts/observability/manage-local-openobserve.sh <command>
+
+Commands:
+  setup             Start OpenObserve + OTEL collector and import the dashboard
+  up                Start the local stack
+  start             Alias for up
+  down              Stop the local stack
+  stop              Alias for down
+  logs              Follow stack logs
+  status            Show stack health and URLs
+  doctor            Validate proxy telemetry freshness across logs, traces, and metrics
+  import-dashboard  Import the NeuroLink proxy dashboard and dedupe by title
+EOF
+}
+
+load_env
+
+: "${NEUROLINK_OPENOBSERVE_USER:=root@example.com}"
+: "${NEUROLINK_OPENOBSERVE_PASSWORD:=Complexpass#123}"
+: "${NEUROLINK_OPENOBSERVE_ORG:=default}"
+: "${NEUROLINK_OPENOBSERVE_HTTP_PORT:=5080}"
+: "${NEUROLINK_OPENOBSERVE_GRPC_PORT:=5081}"
+: "${NEUROLINK_OTLP_GRPC_PORT:=14317}"
+: "${NEUROLINK_OTLP_HTTP_PORT:=14318}"
+: "${NEUROLINK_OTEL_HEALTH_PORT:=14333}"
+: "${NEUROLINK_OTEL_METRICS_PORT:=18888}"
+: "${NEUROLINK_OTEL_PPROF_PORT:=11777}"
+: "${NEUROLINK_OBSERVABILITY_PROJECT_NAME:=neurolink-proxy-observability}"
+: "${NEUROLINK_PROXY_STREAM_HEADER:=neurolink-proxy}"
+: "${NEUROLINK_OPENOBSERVE_URL:=http://localhost:${NEUROLINK_OPENOBSERVE_HTTP_PORT}}"
+: "${NEUROLINK_OPENOBSERVE_OTLP_ENDPOINT:=http://openobserve:5080/api/${NEUROLINK_OPENOBSERVE_ORG}}"
+
+if [[ -z "${NEUROLINK_OPENOBSERVE_BASIC_AUTH:-}" ]]; then
+  encoded_auth="$(printf '%s' "${NEUROLINK_OPENOBSERVE_USER}:${NEUROLINK_OPENOBSERVE_PASSWORD}" | base64 | tr -d '\n')"
+  export NEUROLINK_OPENOBSERVE_BASIC_AUTH="Basic ${encoded_auth}"
+fi
+
+export NEUROLINK_OPENOBSERVE_USER
+export NEUROLINK_OPENOBSERVE_PASSWORD
+export NEUROLINK_OPENOBSERVE_ORG
+export NEUROLINK_OPENOBSERVE_HTTP_PORT
+export NEUROLINK_OPENOBSERVE_GRPC_PORT
+export NEUROLINK_OTLP_GRPC_PORT
+export NEUROLINK_OTLP_HTTP_PORT
+export NEUROLINK_OTEL_HEALTH_PORT
+export NEUROLINK_OTEL_METRICS_PORT
+export NEUROLINK_OTEL_PPROF_PORT
+export NEUROLINK_OBSERVABILITY_PROJECT_NAME
+export NEUROLINK_PROXY_STREAM_HEADER
+export NEUROLINK_OPENOBSERVE_URL
+export NEUROLINK_OPENOBSERVE_OTLP_ENDPOINT
+
+select_compose
+
+command="${1:-setup}"
+
+case "${command}" in
+  setup)
+    compose up -d
+    wait_for_http "OpenObserve" "${NEUROLINK_OPENOBSERVE_URL}/healthz"
+    wait_for_http "OTEL collector" "http://localhost:${NEUROLINK_OTEL_HEALTH_PORT}/"
+    node "${IMPORT_SCRIPT}" --replace-by-title
+    cat <<EOF
+Local proxy observability is ready.
+
+OpenObserve UI: ${NEUROLINK_OPENOBSERVE_URL}
+OpenObserve login user: ${NEUROLINK_OPENOBSERVE_USER}
+OpenObserve password source: ${ENV_FILE} (NEUROLINK_OPENOBSERVE_PASSWORD)
+OTLP HTTP endpoint: http://localhost:${NEUROLINK_OTLP_HTTP_PORT}
+
+Set this before starting the proxy:
+  export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:${NEUROLINK_OTLP_HTTP_PORT}
+EOF
+    ;;
+  up|start)
+    compose up -d
+    ;;
+  down|stop)
+    compose down
+    ;;
+  logs)
+    compose logs -f
+    ;;
+  status)
+    print_status
+    ;;
+  doctor)
+    node "${DOCTOR_SCRIPT}"
+    ;;
+  import-dashboard)
+    node "${IMPORT_SCRIPT}" --replace-by-title
+    ;;
+  help|-h|--help)
+    print_usage
+    ;;
+  *)
+    print_usage >&2
+    exit 1
+    ;;
+esac

package/scripts/observability/otel-collector.proxy-observability.yaml

@@ -0,0 +1,78 @@
+# OpenTelemetry Collector configuration dedicated to the NeuroLink proxy.
+#
+# Active OpenObserve streams created by this setup:
+#   - Logs:   neurolink_proxy
+#   - Traces: neurolink_proxy
+#   - Metrics: proxy_* (metric name becomes the stream)
+
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  memory_limiter:
+    check_interval: 1s
+    limit_mib: 512
+    spike_limit_mib: 128
+
+  batch:
+    timeout: 1s
+    send_batch_size: 1024
+    send_batch_max_size: 2048
+
+  filter/healthcheck:
+    error_mode: ignore
+    traces:
+      span:
+        - 'IsMatch(name, ".*health.*") or IsMatch(name, ".*healthz.*") or IsMatch(name, ".*ready.*")'
+
+exporters:
+  otlphttp/openobserve:
+    endpoint: ${env:NEUROLINK_OPENOBSERVE_OTLP_ENDPOINT}
+    headers:
+      Authorization: ${env:NEUROLINK_OPENOBSERVE_BASIC_AUTH}
+      stream-name: ${env:NEUROLINK_PROXY_STREAM_HEADER}
+    tls:
+      insecure: true
+
+extensions:
+  health_check:
+    endpoint: 0.0.0.0:13133
+
+  pprof:
+    endpoint: 0.0.0.0:1777
+
+service:
+  extensions: [health_check, pprof]
+
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [memory_limiter, filter/healthcheck, batch]
+      exporters: [otlphttp/openobserve]
+
+    metrics:
+      receivers: [otlp]
+      processors: [memory_limiter, batch]
+      exporters: [otlphttp/openobserve]
+
+    logs:
+      receivers: [otlp]
+      processors: [memory_limiter, batch]
+      exporters: [otlphttp/openobserve]
+
+  telemetry:
+    logs:
+      level: info
+    metrics:
+      level: detailed
+      readers:
+        - pull:
+            exporter:
+              prometheus:
+                host: "0.0.0.0"
+                port: 8888

package/scripts/observability/proxy-observability.env.example

@@ -0,0 +1,23 @@
+# Copy this file to scripts/observability/proxy-observability.env only if the
+# defaults collide with your machine or you want different credentials.
+
+NEUROLINK_OPENOBSERVE_USER=root@example.com
+NEUROLINK_OPENOBSERVE_PASSWORD=Complexpass#123
+NEUROLINK_OPENOBSERVE_ORG=default
+
+# Host ports exposed by the local stack.
+NEUROLINK_OPENOBSERVE_HTTP_PORT=5080
+NEUROLINK_OPENOBSERVE_GRPC_PORT=5081
+NEUROLINK_OTLP_GRPC_PORT=14317
+NEUROLINK_OTLP_HTTP_PORT=14318
+NEUROLINK_OTEL_HEALTH_PORT=14333
+NEUROLINK_OTEL_METRICS_PORT=18888
+NEUROLINK_OTEL_PPROF_PORT=11777
+
+# Optional names if you want multiple local stacks in parallel.
+# NEUROLINK_OBSERVABILITY_PROJECT_NAME=neurolink-proxy-observability
+# NEUROLINK_OPENOBSERVE_VOLUME_NAME=neurolink-openobserve-data
+
+# The collector exports proxy telemetry into this OpenObserve stream header.
+# OpenObserve normalizes the logs and traces stream name to "neurolink_proxy".
+# NEUROLINK_PROXY_STREAM_HEADER=neurolink-proxy