From 10f539c66794af849fa350dd4e5df67f5a52ad8d Mon Sep 17 00:00:00 2001 From: Sanja Malovic <48502315+unjica@users.noreply.github.com> Date: Wed, 21 Oct 2026 11:08:52 +0200 Subject: [PATCH 1/4] docs(node): Express error handler and CommonJS snippets --- apps/dashboard/lib/sdk-setup-snippets.ts | 30 ++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/apps/dashboard/lib/sdk-setup-snippets.ts b/apps/dashboard/lib/sdk-setup-snippets.ts index d60f3e4d..fe37ccb5 100644 --- a/apps/dashboard/lib/sdk-setup-snippets.ts +++ b/apps/dashboard/lib/sdk-setup-snippets.ts @@ -172,6 +172,36 @@ app.use((req, res, next) => { }); });`; +export const nodeExpressErrorHandler = `import express from "express"; +import { init, middleware, trackError } from "@telemetry-tracker/node"; + +init({ + ingestUrl: process.env.TELEMETRY_INGEST_URL || "${HOSTED_API_URL}", + app: "my-api", + apiKey: process.env.TELEMETRY_API_KEY, +}); + +const app = express(); +app.use(middleware()); + +// ... your routes ... + +// Error-handling middleware: four arguments, registered after all routes. +app.use((err, req, res, next) => { + trackError(err, { method: req.method, url: req.originalUrl }); + next(err); // keep Express's default error response (or send your own) +});`; + +export const nodeCommonJs = `// CommonJS file (.cjs, or "type" is not "module"): load the ESM package with import() +async function main() { + const { init, trackEvent, flush } = await import("@telemetry-tracker/node"); + init({ ingestUrl: process.env.TELEMETRY_INGEST_URL || "${HOSTED_API_URL}", app: "my-script", apiKey: process.env.TELEMETRY_API_KEY }); + trackEvent("script_finished"); + await flush(); +} + +main();`; + export const nodeTestError = `import { trackError } from "@telemetry-tracker/node"; trackError(new Error("Test error from Node.js"), { route: "/health" });`; From f9baa1e6012767a1cb16ae2c12fb59908ec53866 Mon Sep 17 00:00:00 2001 From: Sanja Malovic <48502315+unjica@users.noreply.github.com> Date: Wed, 21 Oct 2026 11:08:53 +0200 Subject: [PATCH 2/4] docs(node): shared setup snippet, ESM-only note, Express error handler --- apps/dashboard/app/docs/node/page.tsx | 38 ++++++++++++++++++--------- 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/apps/dashboard/app/docs/node/page.tsx b/apps/dashboard/app/docs/node/page.tsx index 37f69d9c..88335fe7 100644 --- a/apps/dashboard/app/docs/node/page.tsx +++ b/apps/dashboard/app/docs/node/page.tsx @@ -3,6 +3,8 @@ import Link from "next/link"; import { CodeBlock } from "@/app/components/docs/CodeBlock"; import { DocsAlsoSee } from "@/app/components/docs/DocsAlsoSee"; import { DocsArticle } from "@/app/components/docs/DocsArticle"; +import { HOSTED_API_URL } from "@/lib/hosted-cloud"; +import { nodeCommonJs, nodeExpressErrorHandler, nodeSetup } from "@/lib/sdk-setup-snippets"; export const metadata: Metadata = { title: "Node.js", @@ -35,19 +37,23 @@ npm install @telemetry-tracker/node`}

Call init() as early as possible (e.g. at the top of your entry file):

- +

+ ingestUrl is required: the SDK has no built-in default. The fallback above is + the hosted API ({HOSTED_API_URL}); set TELEMETRY_INGEST_URL to + your own API when self-hosting. +

-trackEvent("server_started", { version: "1.0.0" }); -trackError(new Error("DB connection failed"), { db: "primary" });`} - /> +

ES modules only

+

+ @telemetry-tracker/node is published as an ES module only: its package.json sets{" "} + "type": "module" and exports only an import condition. Use{" "} + import in .mjs files or packages with{" "} + "type": "module". require("@telemetry-tracker/node") is not + supported. From CommonJS code, load it with a dynamic import() and await{" "} + flush() inside an async function: +

+

Short-lived scripts and jobs

@@ -110,6 +116,14 @@ app.use((req, res, next) => { .

+

Express error handler

+

+ Errors that Express catches in a route never reach the global handlers. Report them from an + error-handling middleware (four arguments, registered after your routes) with{" "} + trackError(), then pass the error on: +

+ + Date: Wed, 21 Oct 2026 11:08:54 +0200 Subject: [PATCH 3/4] docs(node): ingest URL note and Express error handler on guide --- .../dashboard/app/error-tracking/nodejs/page.tsx | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/apps/dashboard/app/error-tracking/nodejs/page.tsx b/apps/dashboard/app/error-tracking/nodejs/page.tsx index a498ffd8..70d4ad99 100644 --- a/apps/dashboard/app/error-tracking/nodejs/page.tsx +++ b/apps/dashboard/app/error-tracking/nodejs/page.tsx @@ -11,7 +11,8 @@ import { webPageJsonLd, } from "@/lib/marketing-guide-metadata"; import { marketingSiteOrigin } from "@/lib/marketing-json-ld"; -import { nodeInstall, nodeMiddleware, nodeSetup, nodeTestError } from "@/lib/sdk-setup-snippets"; +import { nodeExpressErrorHandler, nodeInstall, nodeMiddleware, nodeSetup, nodeTestError } from "@/lib/sdk-setup-snippets"; +import { HOSTED_API_URL } from "@/lib/hosted-cloud"; const PATH = "/error-tracking/nodejs"; const TITLE = "Node.js Error Tracking"; @@ -111,6 +112,12 @@ export default function NodeJsErrorTrackingPage() {

Minimal setup

Call init at the top of your entry file. Keep the API key in an environment variable:

+

+ ingestUrl is required: the SDK has no built-in default. The fallback above is + the hosted API ({HOSTED_API_URL}); point TELEMETRY_INGEST_URL at + your own API when self-hosting. The package is ES modules only; see the{" "} + Node.js docs for use from CommonJS. +

Send a test error

@@ -127,6 +134,13 @@ export default function NodeJsErrorTrackingPage() {

+

Express error handler

+

+ Errors Express catches in a route do not reach the global handlers. Report them from an + error-handling middleware registered after your routes: +

+ +

What you will see

Server errors group like browser issues: fingerprint, stack, and the context object you From f1f1d1241652c4d1fef1a1491b44de0a0507efee Mon Sep 17 00:00:00 2001 From: Sanja Malovic <48502315+unjica@users.noreply.github.com> Date: Wed, 21 Oct 2026 11:13:41 +0200 Subject: [PATCH 4/4] docs(node): escape quotes for lint --- apps/dashboard/app/docs/node/page.tsx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/dashboard/app/docs/node/page.tsx b/apps/dashboard/app/docs/node/page.tsx index 88335fe7..c8ae7f5e 100644 --- a/apps/dashboard/app/docs/node/page.tsx +++ b/apps/dashboard/app/docs/node/page.tsx @@ -47,9 +47,9 @@ npm install @telemetry-tracker/node`}

ES modules only

@telemetry-tracker/node is published as an ES module only: its package.json sets{" "} - "type": "module" and exports only an import condition. Use{" "} + {`"type": "module"`} and exports only an import condition. Use{" "} import in .mjs files or packages with{" "} - "type": "module". require("@telemetry-tracker/node") is not + {`"type": "module"`}. {`require("@telemetry-tracker/node")`} is not supported. From CommonJS code, load it with a dynamic import() and await{" "} flush() inside an async function: