aiko-monitor

Node SDK for sending monitored HTTP events to Aiko Monitor.

Verbose install verification

Pass verbose: true to aiko.init(...) while installing the SDK. The SDK keeps ingest behavior unchanged and prints useful details for normal captured requests, including whether monitor accepts the first event.

Example output:

[aiko] verbose init sdk=node:0.0.11 endpoint=https://monitor.aikocorp.ai/api/ingest project_key=pk_AAA...AAAA queue_size=5000 max_concurrent_sends=5
[aiko] verbose captured event_id=evt_... method=GET endpoint=/hello status=200 duration_ms=4
[aiko] verbose queued event_id=evt_... queue_depth=1 queue_size=5000
[aiko] verbose send attempt event_id=evt_... attempt=1 max_attempts=3 method=GET endpoint=/hello payload_bytes=382
[aiko] verbose send accepted event_id=evt_... status=202 request_id=req_... latency_ms=91
[aiko] verbose install verified: monitor accepted first event

Actor extraction

Actor extraction is opt-in. Configure where the auth token lives and which JWT claims map to actor fields. The SDK decodes JWT payloads locally and sends only actor.provider, actor.id, actor.email, and actor.org_id. It does not send the token.

For bearer tokens in the Authorization header:

import aiko from "aiko-monitor";

const monitor = aiko.init({
  projectKey: process.env.AIKO_PROJECT_KEY,
  secretKey: process.env.AIKO_SECRET_KEY,
  actor: {
    provider: "jwt",
    token: {
      header: {
        name: "authorization",
        extract: { type: "bearer" },
      },
    },
    claims: {
      id: "sub",
      email: "email",
    },
  },
});

For JSON cookies that contain the JWT under a field such as access_token:

const monitor = aiko.init({
  projectKey: process.env.AIKO_PROJECT_KEY,
  secretKey: process.env.AIKO_SECRET_KEY,
  actor: {
    provider: "jwt",
    token: {
      cookie: {
        name: "aiko_auth_token",
        extract: { type: "json", path: "access_token" },
      },
    },
    claims: {
      id: "uid",
      email: "sub",
      orgId: "org_id",
    },
  },
});

For Supabase auth cookies, configure the cookie name and the claims explicitly. The cookie name is usually sb-<project-ref>-auth-token.

const monitor = aiko.init({
  projectKey: process.env.AIKO_PROJECT_KEY,
  secretKey: process.env.AIKO_SECRET_KEY,
  actor: {
    provider: "supabase",
    token: {
      cookie: {
        name: "sb-<project-ref>-auth-token",
      },
    },
    claims: {
      id: "sub",
      email: "email",
    },
  },
});

For opaque or encrypted sessions, use a custom resolver and return the actor fields yourself:

const monitor = aiko.init({
  projectKey: process.env.AIKO_PROJECT_KEY,
  secretKey: process.env.AIKO_SECRET_KEY,
  actor: {
    provider: "custom",
    async resolve(ctx) {
      const user = await userFromRequest(ctx.request);
      if (!user) return undefined;
      return {
        provider: "custom",
        id: user.id,
        email: user.email,
        org_id: user.orgId,
      };
    },
  },
});

For nested claims, use dot paths such as user.id or claims.email.

Expected JWT payload shape:

{
  "exp": 1781326327,
  "sub": "8e9ccf29-7838-46e3-bafc-b0a91f14b20a",
  "email": "[email protected]"
}

SvelteKit (@sveltejs/adapter-node)

Use instrumentation.server for the Node transport and hooks.server for internal subrequests:

// src/lib/server/monitor.js
import aiko from "aiko-monitor";

const projectKey = process.env.AIKO_PROJECT_KEY || "";
const secretKey = process.env.AIKO_SECRET_KEY || "";
const endpoint = process.env.AIKO_ENDPOINT || "";

export const monitor =
  !projectKey || !secretKey || !endpoint
    ? aiko.init({ enabled: false })
    : aiko.init({ projectKey, secretKey, endpoint });

// src/instrumentation.server.js
import { monitor } from "$lib/server/monitor";

monitor.instrumentSvelteKitNode();

// src/hooks.server.js
import { monitor } from "$lib/server/monitor";

export const handleFetch = monitor.svelteKitHandleFetch();

// svelte.config.js
export default {
  kit: {
    experimental: {
      instrumentation: {
        server: true,
      },
    },
  },
};

This path is intended for Node-hosted SvelteKit via @sveltejs/adapter-node. The Node transport captures normal requests. handleFetch captures internal same-origin event.fetch(...) subrequests without double-counting them.