npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@othmanhaba/apm-node

v0.1.0

Published

Falak APM for Node.js, Bun and Deno: an OpenTelemetry preset that exports Nightwatch-style request, outgoing request, query, cache and exception telemetry to the local falak-agent.

Readme

@othmanhaba/apm-node

Falak APM for Node.js 20+, Bun and Deno. It is a thin preset over the official OpenTelemetry JS SDK. It exports traces, logs and metrics as OTLP/HTTP JSON to the local falak-agent (http://127.0.0.1:4318). Spans are normalised to the Falak telemetry contract (falak.event.type = request / outgoing_request / query / cache).

Install

npm i @othmanhaba/apm-node      # or: bun add @othmanhaba/apm-node / pnpm add @othmanhaba/apm-node

Node.js

Load it before your app so that auto-instrumentation can patch modules as they are imported:

node --import @othmanhaba/apm-node/register server.js
# or: NODE_OPTIONS="--import @othmanhaba/apm-node/register"

You can also put import '@othmanhaba/apm-node/register'; on the first line of the entry file. That covers CommonJS modules and Node built-ins. Use --import when the app loads pg/express/… through ESM import.

Auto-instrumented: http/https (incoming and outgoing), undici/global fetch, pg, mysql2, ioredis, express and fastify. Each instrumentation turns on only when its module is loaded.

Programmatic setup:

import { start, shutdown } from '@othmanhaba/apm-node';

start({ serviceName: 'shop', sampleRate: 0.5, redactKeys: ['password', 'token', 'ssn'] });
process.on('SIGTERM', () => shutdown().finally(() => process.exit(0)));

Next.js

instrumentation.ts in the project root (see examples/next-instrumentation.ts):

export async function register() {
  const { registerFalak } = await import('@othmanhaba/apm-node/next');
  await registerFalak();
}

Only the Node.js runtime is instrumented. Next's own spans are exported and mapped too: the route comes from next.route.

Nuxt / Nitro

// server/plugins/falak.ts
import falak from '@othmanhaba/apm-node/nitro';
export default defineNitroPlugin(falak);

The plugin starts the SDK and records errors from Nitro's error hook as unhandled. It also sets http.route from the matched route. On presets without Node http instrumentation (Bun, Deno), it opens a request span per request.

Bun / Deno / fetch-style handlers

Node's auto-instrumentation does not hook Bun.serve or Deno.serve. On those runtimes start() uses a lightweight tracer provider with the same exporters, and you wrap your handler:

import { start, withFalakRequest, setUser, recordException } from '@othmanhaba/apm-node';

start();

Bun.serve({
  fetch: withFalakRequest(handler, {
    route: (req) => '/users/:id',          // low-cardinality route template
    user: (req) => session(req)?.userId,   // enduser.id
    captureHeaders: ['x-request-id'],
  }),
});

The wrapper continues an incoming traceparent. It records thrown errors as falak.exception.handled=false with an ERROR status and rethrows them. Responses with status 5xx also mark the span ERROR. The same wrapper works for Hono (withFalakRequest(app.fetch)), Deno and Next route handlers. See examples/.

Exceptions

import { recordException } from '@othmanhaba/apm-node';

try { await charge(); } catch (e) { recordException(e); /* handled=true, span status untouched */ }
recordException(err, { handled: false }); // span → ERROR
  • Every exception span event carries falak.exception.handled. For exceptions recorded by instrumentations, the flag comes from the span status: an ERROR status means the exception escaped.
  • Uncaught exceptions are captured through uncaughtExceptionMonitor, and unhandled rejections are captured too. Both are recorded as handled=false. The process still crashes as it would by default. Set captureProcessErrors: false to opt out.

Configuration

| Option | Env | Default | |---|---|---| | enabled | FALAK_APM_ENABLED | true | | endpoint | FALAK_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_ENDPOINT | http://127.0.0.1:4318 | | serviceName | FALAK_SERVICE_NAME, OTEL_SERVICE_NAME | npm_package_name (the agent overrides it with the site slug) | | sampleRate (root, parent-based) | FALAK_SAMPLE_RATE | 1 | | autoInstrument | FALAK_APM_AUTO_INSTRUMENT | true (Node only) | | logs | FALAK_APM_LOGS | true | | metrics | FALAK_APM_METRICS | true (Node only, 60 s interval) | | redactKeys | | password, token, secret, authorization, cookie, api_key | | redactQueryLiterals | | true | | redact(attributes, eventType) | | none | | captureRequestHeaders | | ['user-agent'] | | captureProcessErrors | | true |

Resource attributes are read from FALAK_SITE_ID, FALAK_SERVER_ID, FALAK_DEPLOYMENT_ID, FALAK_RELEASE_ID, FALAK_ORG_ID and FALAK_ENVIRONMENT (falling back to NODE_ENV). Deployments inject them, and the agent also sets them authoritatively.

Mapping and redaction

The Falak span processor runs before export and does the following:

| Span | falak.event.type | Normalised attributes | |---|---|---| | SERVER + HTTP | request | http.request.method, http.route, http.response.status_code, url.path (from old http.* names when needed); 5xx → ERROR | | CLIENT + HTTP | outgoing_request | http.request.method, url.full, http.response.status_code | | db.system = sql | query | db.system.name, db.query.text, db.namespace, falak.query.connection (host:port) | | ioredis key/value commands | cache | falak.cache.op (hit/miss from the reply, write, forget), falak.cache.key, falak.cache.store |

Redaction then applies:

  • Attribute keys that contain a denylisted word (including captured headers) become [redacted].
  • The same goes for denylisted query parameters in url.full, url.query and http.target, and for a password in the URL userinfo.
  • Quoted SQL literals become ?.
  • Cache keys that contain a denylisted word are redacted.
  • Log record attributes are filtered with the same denylist.
  • Your redact callback runs last. It can change the attributes in place or return a replacement map. A callback that throws is ignored.

Development

bun install
bun run typecheck && bun run build   # tsc → dist/*.js + .d.ts
bun test                             # includes a real `node --import dist/register.js` roundtrip