diff --git a/apps/dashboard/app/docs/node/page.tsx b/apps/dashboard/app/docs/node/page.tsx index 37f69d9c..c8ae7f5e 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: +

+ + 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 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" });`;