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.
65
78%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
View guide
Passed
No findings from the security scan
Fix and improve this skill with Tessl
tessl review fix ./skills/maple-nodejs-style/SKILL.mdUse @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:
node --import ./telemetry.js app.jsFor 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:
@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\//] },
})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.await sdk.shutdown() before the process ends.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.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()
}
})
})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.
If the repo has Sentry, Datadog, New Relic, Honeycomb, Logtail, or a Pino transport, leave them in place alongside Maple.
1a03fa7
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.