OpenParable
Skip to content
← Back to skills

Maple Nodejs Style

Development
maple-nodejs-style

Maple Nodejs Style is an Agent Skill for development published in the MapleTechLabs/maple repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Plain Node.js (Express, Fastify, Hono, Bun) OpenTelemetry style for Maple: NodeSDK + --import bootstrap, native @opentelemetry/api call sites, inline endpoint + ingest key, OTLP HTTP exporters.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/MapleTechLabs/maple/blob/HEAD/skills/maple-nodejs-style/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/maple-nodejs-style, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Maple Node.js style

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

// telemetry.ts
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"

const MAPLE_ENDPOINT = "https://ingest.maple.dev"
const MAPLE_KEY = "MAPLE_TEST" // set by maple-onboard skill on pairing

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

const sdk = new NodeSDK({
	resource: resourceFromAttributes({
		"service.name": "my-node-app",
		"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(
			new OTLPLogExporter({ url: `${MAPLE_ENDPOINT}/v1/logs`, headers }),
		),
	],
	metricReader: new PeriodicExportingMetricReader({
		exporter: new OTLPMetricExporter({
			url: `${MAPLE_ENDPOINT}/v1/metrics`,
			headers,
		}),
	}),
	instrumentations: [getNodeAutoInstrumentations()],
})

sdk.start()

Run the app with the bootstrap loaded first:

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

For TypeScript projects, use the loader the repo already uses (tsx, ts-node/esm, native Bun, etc.) — do not introduce a new loader.

Bootstrap rules

  • HTTP OTLP exporters only, never gRPC. gRPC pulls in native bindings that complicate containers.
  • getNodeAutoInstrumentations() covers HTTP, Express, Fastify, Hono, pg, MySQL, Redis, and many more out of the box. Disable specific instrumentations only when they actively break the app:
    getNodeAutoInstrumentations({
    	"@opentelemetry/instrumentation-fs": { enabled: false },
    })
    
  • For Bun, use the same SDK with bun --preload ./telemetry.ts run app.ts. Bun's HTTP exporter compatibility is good; if you hit an issue, fall back to node for the bootstrap process.

Route handlers and business operations

Use the native API; reach for withSpan from @maple/otel-helpers for bounded operations.

import { trace, metrics } from "@opentelemetry/api"
import { withSpan } from "@maple/otel-helpers"

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

app.post("/orders", async (req, res) => {
	await withSpan(
		"order.submit",
		async (span) => {
			span.setAttributes({
				"tenant.id": req.headers["x-tenant-id"] as string,
				"order.id": req.body.id,
			})
			await chargeOrder(req.body)
			submitted.add(1, { "tenant.id": req.headers["x-tenant-id"] as string })
			res.json({ ok: true })
		},
		{ tracer },
	)
})

Logs

Bridge the existing logger (Pino, Winston, console) through OTLP rather than replacing it. For Pino, install @opentelemetry/instrumentation-pino and include it in instrumentations. For Winston, install @opentelemetry/instrumentation-winston. The user's logger keeps its current sinks; you're adding OTLP underneath so logs carry trace_id / span_id and reach Maple. Do not rip out the existing logger.

Coexistence

If the repo has Sentry, Datadog, New Relic, Honeycomb, Logtail, or a Pino transport, leave them in place. They sit alongside Maple, not instead of it.