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 🙏

© 2024 – Pkg Stats / Ryan Hefner

@nifty-lil-tricks/monitoring

v0.3.1

Published

A selection of useful utilities (or nifty li'l tricks!) for all things monitoring and OpenTelemetry

Downloads

1,607

Readme

@nifty-lil-tricks/monitoring

Latest Version GitHub License Buy us a tree codecov

Note: This is an experimental package under active development. New releases may include breaking changes.

A selection of useful utilities (or nifty li'l tricks!) for all things monitoring and OpenTelemetry.

Table of contents

Installation

Note: this package works with TypeScript v5 or later

npm install @nifty-lil-tricks/monitoring

Experimental stage 2 decorators

If you are using experimental stage 2 decorators, you will need to set the following in your tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Stage 3 decorators

No setup is required.

Features

The following features are supported

Monitoring Decorator

Monitoring Decorator Overview

This decorator wraps all methods of a class in an OpenTelemetry Span. If a parent span cannot be retrieved from the context of the method call, it will not be monitored.

The decorator will not affect any of the underlying functionality and it will also handle any legitimate errors thrown from the underlying method as appropriate.

Exported span for method that passes

A method of name hello on class Service that returns without error will export the following span details by default:

{
  "id": "b98126c289c5c9dc",
  "name": "Service.hello",
  "traceId": "a7b41739082880c506d62152de2e13a1",
  "parentId": "f64d1571cd4a88dd",
  "kind": 0,
  "attributes": {
    "monitoring.method": "hello",
    "monitoring.class": "Service"
  },
  "status": { "code": 1 },
  "timestamp": 1684136794317000,
  "duration": 2010408,
  "events": [],
  "links": []
}
Exported span for method that throws

A method of name hello on class Service that throws an error will export the following span details by default:

{
  "id": "7c5f84a384af9a63",
  "name": "Service.hello",
  "traceId": "931ba33b4ab375ade4f26c7ac93df4ce",
  "parentId": "0182507d0f5f0a85",
  "kind": 0,
  "attributes": {
    "monitoring.method": "hello",
    "monitoring.class": "Service"
  },
  "status": { "code": 2, "message": "Error: something bad happened" },
  "timestamp": 1684136986170000,
  "duration": 502605,
  "events": [],
  "links": []
}

Pre-requisites

Ensure OpenTelemetry tracing is set-up by ensuring:

  • The provider is registered
  • The monitored method is wrapped in the context of a parent span
  • A global context manager is set up

See example set up for a quick guide to getting the above setup.

Wrap all methods of a class in a span

import { Monitor } from "@nifty-lil-tricks/monitoring";
import { promisify } from "node:util";

@Monitor()
class Service {
  async hello(): Promise<void> {
    // Do work
    await promisify(setTimeout)(500);

    // Do nested work
    await this.nested();
  }

  async nested(): Promise<void> {
    // Do work
    await promisify(setTimeout)(1000);
  }
}

Filter allowed methods to monitor

By default, the monitor decorator monitors all non-private methods. One can provide an allowedMethods option to filter the methods that are monitored. This filter can be provided in several types:

  • string[]
  • RegExp
  • (methodName: string) => boolean
Filtering monitored methods by list of strings
import { Monitor } from "@nifty-lil-tricks/monitoring";
import { promisify } from "node:util";

@Monitor({ allowedMethods: ["allowed1", "allowed2"] })
class Service {
  // Not monitored
  notAllowed(): void {}

  // Monitored
  allowed1(): void {}

  // Monitored
  allowed2(): void {}
}
Filtering monitored methods by regex
import { Monitor } from "@nifty-lil-tricks/monitoring";
import { promisify } from "node:util";

@Monitor({ allowedMethods: /^allowed.+/ })
class Service {
  // Not monitored
  notAllowed(): void {}

  // Monitored
  allowed1(): void {}

  // Monitored
  allowed2(): void {}
}
Filtering monitored methods by function
import { Monitor } from "@nifty-lil-tricks/monitoring";
import { promisify } from "node:util";

@Monitor({ allowedMethods: (method) => method.startsWith("allowed") })
class Service {
  // Not monitored
  notAllowed(): void {}

  // Monitored
  allowed1(): void {}

  // Monitored
  allowed2(): void {}
}

Override the default Span kind

By default, the monitor decorator sets the Span Kind to be INTERNAL. This option allows one to override this.

import { Monitor } from "@nifty-lil-tricks/monitoring";
import { promisify } from "node:util";

@Monitor({ spanKind: SpanKind.SERVER })
class Service {
  async hello(): Promise<void> {
    // Do work
    await promisify(setTimeout)(500);
  }
}

Override the inferred class name

By default, the monitor decorator infers the class name from the class. This option allows one to override this behaviour. A use-case for this would be when one has multiple classes of the same name defined.

import { Monitor } from "@nifty-lil-tricks/monitoring";
import { promisify } from "node:util";

@Monitor({ className: "OtherService" })
class Service {
  async hello(): Promise<void> {
    // Do work
    await promisify(setTimeout)(500);
  }
}

Override the default tracer name

By default, the monitor decorator uses the default tracer to record spans. This option allows one to override this behaviour.

import { Monitor } from "@nifty-lil-tricks/monitoring";
import { promisify } from "node:util";

@Monitor({ tracerName: "some-other-tracer" })
class Service {
  async hello(): Promise<void> {
    // Do work
    await promisify(setTimeout)(500);
  }
}

Caveats

Private methods as defined here are not monitoring by this decorator.

import { Monitor } from "@nifty-lil-tricks/monitoring";
import { promisify } from "node:util";

@Monitor({ tracerName: "some-other-tracer" })
class Service {
  // Monitored
  async hello(): Promise<void> {
    // Not monitored
    await this.#privateMethod(())
  }

  async #privateMethod(): Promise<void> {
    // Do work
    await promisify(setTimeout)(500);
  }
}

API

The API docs can be found here

Examples

Examples can be found here.

Basic example

To run the examples/basic.ts example, run the following:

  • Ensure Docker is running
  • Start the Jaeger collector: npm run start:collector
  • Run the example: npm run example:basic
  • Navigate to the Jaeger UI: http://localhost:16686

Example exported trace

Nestjs example

To run the examples/basic.ts example, run the following:

  • Ensure Docker is running
  • Start the Jaeger collector: npm run start:collector
  • Run the example: npm run example:nestjs
  • Make a request to the app: curl http://localhost:3000/
  • Navigate to the Jaeger UI: http://localhost:16686

Example exported trace

Support

| Platform Version | Supported | Notes | | ---------------- | ------------------ | --------------------------------------------------------- | | Node.JS v18 | :white_check_mark: | TypeScript v5+ for typings | | Node.JS v20 | :white_check_mark: | TypeScript v5+ for typings | | Deno v1 | :x: | Will be supported when OpenTelemetry is supported in Deno | | Web Browsers | :x: | Coming soon |

Useful links

  • For more information on OpenTelemetry, visit: https://opentelemetry.io/
  • For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
  • For help or feedback on this project, join us in GitHub Discussions

License

Nifty li'l tricks packages are 100% free and open-source, under the MIT license.

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Contributions

Contributions, issues and feature requests are very welcome. If you are using this package and fixed a bug for yourself, please consider submitting a PR!