maple-nodejs-style

Maple Node.js style

Use @opentelemetry/sdk-node loaded with --import (Bun: --preload) so the SDK starts before any framework code runs.

// telemetry.ts
import { register } from "node:module"
import { NodeSDK } from "@opentelemetry/sdk-node"
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node"
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"
import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http"
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http"
import { BatchLogRecordProcessor } from "@opentelemetry/sdk-logs"
import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics"
import { resourceFromAttributes } from "@opentelemetry/resources"

// ESM apps only: lets auto-instrumentation patch ESM-only packages. Omit for CommonJS.
register("@opentelemetry/instrumentation/hook.mjs", import.meta.url)

const MAPLE_ENDPOINT = "https://ingest.maple.dev" // EU: https://ingest.eu.maple.dev const MAPLE_KEY = "MAPLE_TEST" // public ingest key (maple_pk_…), or MAPLE_TEST until the user has one

const headers = { authorization: Bearer ${MAPLE_KEY} }

const sdk = new NodeSDK({ resource: resourceFromAttributes({ "service.name": "my-node-app", "service.version": "1.4.2", // package.json version, a release tag, or the commit SHA "deployment.environment.name": process.env.NODE_ENV ?? "development", "vcs.repository.url.full": "https://github.com/acme/my-node-app", "vcs.ref.head.revision": process.env.RAILWAY_GIT_COMMIT_SHA ?? process.env.GITHUB_SHA ?? process.env.GIT_COMMIT, }), traceExporter: new OTLPTraceExporter({ url: ${MAPLE_ENDPOINT}/v1/traces, headers, }), logRecordProcessors: [ new BatchLogRecordProcessor({ exporter: new OTLPLogExporter({ url: ${MAPLE_ENDPOINT}/v1/logs, headers }), }), ], metricReaders: [ new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter({ url: ${MAPLE_ENDPOINT}/v1/metrics, headers, }), }), ], instrumentations: [getNodeAutoInstrumentations()], })

sdk.start()

// Flush buffered spans, logs, and metrics before exit. If the app already handles // SIGTERM, call sdk.shutdown() from that handler instead. for (const signal of ["SIGTERM", "SIGINT"]) { process.once(signal, () => { sdk .shutdown() .catch((err) => console.error("telemetry shutdown failed", err)) .finally(() => process.exit(0)) }) }


Run the app with the bootstrap loaded first:

```bash
node --import ./telemetry.js app.js

For TypeScript projects, use the loader the repo already uses (tsx, ts-node/esm, native Bun). Do not introduce a new loader. For ESM apps, keep the register(...) hook call and add @opentelemetry/instrumentation to package.json.

Match the installed SDK versions; the wrong shape starts cleanly and then drops data:

Current @opentelemetry/sdk-logs takes new BatchLogRecordProcessor({ exporter }). Older releases took the exporter as the first argument. With the wrong form, every log export throws inside the SDK and no log leaves the process. Check the installed .d.ts.
metricReaders (array) replaced metricReader.

If the app fails at startup after adding the ESM hook, a dependency is incompatible with it. openai@4 is a known case ("you must import 'openai/shims/node'"). Exclude that package from the hook, then instrument it manually or upgrade it:

register("@opentelemetry/instrumentation/hook.mjs", import.meta.url, {
	data: { exclude: [/\/node_modules\/openai\//] },
})

Bootstrap rules

HTTP OTLP exporters only, never gRPC. gRPC pulls in native bindings that complicate containers.
getNodeAutoInstrumentations() covers HTTP, fetch (undici), Express, Fastify, pg, MySQL, Redis, and more. Frameworks without their own instrumentation (Hono on @hono/node-server) are still traced at the HTTP server layer. Disable an instrumentation only when it breaks the app:
```
getNodeAutoInstrumentations({
	"@opentelemetry/instrumentation-fs": { enabled: false },
})
```
getNodeAutoInstrumentations() pulls in about 200 packages. For a small service, listing the specific @opentelemetry/instrumentation-* packages it needs is a fine alternative.
CLIs and one-shot scripts exit before the batch and metric intervals fire: await sdk.shutdown() before the process ends.
For Bun, use the same SDK with bun --preload ./telemetry.ts app.ts. Bun ignores Node's module hooks, so some auto-instrumentations do not fire. Add manual spans where auto-instrumentation is blind.

Route handlers and business operations

Use the native API: tracer.startActiveSpan with try / catch / finally for bounded operations, as in maple-onboarding-style.

import { metrics, SpanStatusCode, trace } from "@opentelemetry/api"

const tracer = trace.getTracer("orders.api")
const meter = metrics.getMeter("orders.api")
const submitted = meter.createCounter("orders.submitted")

app.post("/orders", async (req, res) => {
	const tenantId = req.headers["x-tenant-id"] as string
	await tracer.startActiveSpan("order.submit", async (span) => {
		try {
			span.setAttributes({ "tenant.id": tenantId, "order.id": req.body.id })
			await chargeOrder(req.body)
			submitted.add(1, { "tenant.id": tenantId })
			res.json({ ok: true })
		} catch (err) {
			span.recordException(err as Error)
			span.setStatus({ code: SpanStatusCode.ERROR, message: (err as Error).message })
			throw err
		} finally {
			span.end()
		}
	})
})

Logs

Bridge the existing logger through OTLP. Do not replace it. getNodeAutoInstrumentations() already includes the Pino, Winston, and Bunyan instrumentations: they inject trace_id / span_id into records and forward them to the logRecordProcessors configured above. Winston forwarding also needs @opentelemetry/winston-transport installed. console.* is not bridged. The user's logger keeps its current sinks.

Coexistence

If the repo has Sentry, Datadog, New Relic, Honeycomb, Logtail, or a Pino transport, leave them in place alongside Maple.

About this skill

Bootstrap rules

Route handlers and business operations

Logs

Coexistence