{"id":13454921,"url":"https://github.com/nifty-lil-tricks/monitoring","last_synced_at":"2026-03-09T02:32:19.089Z","repository":{"id":165352974,"uuid":"640699932","full_name":"nifty-lil-tricks/monitoring","owner":"nifty-lil-tricks","description":"A selection of nifty lil tricks for all things monitoring","archived":false,"fork":false,"pushed_at":"2024-09-03T22:34:13.000Z","size":650,"stargazers_count":5,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-03T12:54:50.339Z","etag":null,"topics":["library","monitoring","nodejs","opentelemetry","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nifty-lil-tricks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-14T23:41:44.000Z","updated_at":"2024-11-04T21:01:05.000Z","dependencies_parsed_at":"2023-11-25T17:12:34.454Z","dependency_job_id":"0edc776b-2120-42eb-9b47-f76c0aed0319","html_url":"https://github.com/nifty-lil-tricks/monitoring","commit_stats":null,"previous_names":["nifty-lil-tricks/monitoring"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/nifty-lil-tricks/monitoring","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nifty-lil-tricks%2Fmonitoring","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nifty-lil-tricks%2Fmonitoring/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nifty-lil-tricks%2Fmonitoring/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nifty-lil-tricks%2Fmonitoring/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nifty-lil-tricks","download_url":"https://codeload.github.com/nifty-lil-tricks/monitoring/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nifty-lil-tricks%2Fmonitoring/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30280855,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:23:26.802Z","status":"ssl_error","status_checked_at":"2026-03-09T02:22:46.175Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["library","monitoring","nodejs","opentelemetry","typescript"],"created_at":"2024-07-31T08:00:59.446Z","updated_at":"2026-03-09T02:32:19.071Z","avatar_url":"https://github.com/nifty-lil-tricks.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"![Nifty li'l tricks Logo](https://raw.githubusercontent.com/nifty-lil-tricks/assets/main/nifty-lil-tricks-logo.png)\n\n# @nifty-lil-tricks/monitoring\n\n[![Latest Version](https://img.shields.io/npm/v/@nifty-lil-tricks/monitoring?style=flat-square)](https://www.npmjs.com/package/@nifty-lil-tricks/monitoring)\n[![GitHub License](https://img.shields.io/github/license/nifty-lil-tricks/monitoring?style=flat-square)](https://raw.githubusercontent.com/nifty-lil-tricks/monitoring/main/LICENSE)\n[![Buy us a tree](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-lightgreen)](https://plant.treeware.earth/nifty-lil-tricks/monitoring)\n[![codecov](https://codecov.io/gh/nifty-lil-tricks/monitoring/branch/main/graph/badge.svg)](https://codecov.io/gh/nifty-lil-tricks/monitoring)\n\n**Note: This is an experimental package under active development. New releases\nmay include breaking changes.**\n\nA selection of useful utilities (or nifty li'l tricks!) for all things\nmonitoring and [OpenTelemetry](https://opentelemetry.io/).\n\n## Table of contents\n\n- [Installation](#installation)\n- [Features](#features)\n- [API](#api)\n- [Examples](#examples)\n- [Support](#support)\n- [Useful links](#useful-links)\n- [License](#license)\n- [Contributions](#contributions)\n\n## Installation\n\n**Note: this package works with TypeScript v5 or later**\n\n```shell\nnpm install @nifty-lil-tricks/monitoring\n```\n\n### Experimental stage 2 decorators\n\nIf you are using experimental stage 2 decorators, you will need to set the\nfollowing in your `tsconfig.json`:\n\n```json\n{\n  \"compilerOptions\": {\n    \"experimentalDecorators\": true,\n    \"emitDecoratorMetadata\": true\n  }\n}\n```\n\n### Stage 3 decorators\n\nNo setup is required.\n\n## Features\n\nThe following features are supported\n\n- [Monitoring decorator](#monitoring-decorator) that wraps all methods of a\n  class in an\n  [OpenTelemetry Span](https://opentelemetry.io/docs/concepts/glossary/#span)\n  automatically tracing every method on the class.\n\n### Monitoring Decorator\n\n- [@nifty-lil-tricks/monitoring](#nifty-lil-tricksmonitoring)\n  - [Table of contents](#table-of-contents)\n  - [Installation](#installation)\n    - [Experimental stage 2 decorators](#experimental-stage-2-decorators)\n    - [Stage 3 decorators](#stage-3-decorators)\n  - [Features](#features)\n    - [Monitoring Decorator](#monitoring-decorator)\n      - [Monitoring Decorator Overview](#monitoring-decorator-overview)\n        - [Exported span for method that passes](#exported-span-for-method-that-passes)\n        - [Exported span for method that throws](#exported-span-for-method-that-throws)\n      - [Pre-requisites](#pre-requisites)\n      - [Wrap all methods of a class in a span](#wrap-all-methods-of-a-class-in-a-span)\n      - [Filter allowed methods to monitor](#filter-allowed-methods-to-monitor)\n        - [Filtering monitored methods by list of strings](#filtering-monitored-methods-by-list-of-strings)\n        - [Filtering monitored methods by regex](#filtering-monitored-methods-by-regex)\n        - [Filtering monitored methods by function](#filtering-monitored-methods-by-function)\n      - [Override the default Span kind](#override-the-default-span-kind)\n      - [Override the inferred class name](#override-the-inferred-class-name)\n      - [Override the default tracer name](#override-the-default-tracer-name)\n      - [Caveats](#caveats)\n  - [API](#api)\n  - [Examples](#examples)\n    - [Basic example](#basic-example)\n    - [Nestjs example](#nestjs-example)\n  - [Support](#support)\n  - [Useful links](#useful-links)\n  - [License](#license)\n  - [Contributions](#contributions)\n\n#### Monitoring Decorator Overview\n\nThis decorator wraps all methods of a class in an\n[OpenTelemetry Span](https://opentelemetry.io/docs/concepts/glossary/#span). If\na parent span cannot be retrieved from the context of the method call, it will\n**not** be monitored.\n\nThe decorator will not affect any of the underlying functionality and it will\nalso handle any legitimate errors thrown from the underlying method as\nappropriate.\n\n##### Exported span for method that passes\n\nA method of name `hello` on class `Service` that returns without error will\nexport the following span details by default:\n\n```json\n{\n  \"id\": \"b98126c289c5c9dc\",\n  \"name\": \"Service.hello\",\n  \"traceId\": \"a7b41739082880c506d62152de2e13a1\",\n  \"parentId\": \"f64d1571cd4a88dd\",\n  \"kind\": 0,\n  \"attributes\": {\n    \"monitoring.method\": \"hello\",\n    \"monitoring.class\": \"Service\"\n  },\n  \"status\": { \"code\": 1 },\n  \"timestamp\": 1684136794317000,\n  \"duration\": 2010408,\n  \"events\": [],\n  \"links\": []\n}\n```\n\n##### Exported span for method that throws\n\nA method of name `hello` on class `Service` that throws an error will export the\nfollowing span details by default:\n\n```json\n{\n  \"id\": \"7c5f84a384af9a63\",\n  \"name\": \"Service.hello\",\n  \"traceId\": \"931ba33b4ab375ade4f26c7ac93df4ce\",\n  \"parentId\": \"0182507d0f5f0a85\",\n  \"kind\": 0,\n  \"attributes\": {\n    \"monitoring.method\": \"hello\",\n    \"monitoring.class\": \"Service\"\n  },\n  \"status\": { \"code\": 2, \"message\": \"Error: something bad happened\" },\n  \"timestamp\": 1684136986170000,\n  \"duration\": 502605,\n  \"events\": [],\n  \"links\": []\n}\n```\n\n#### Pre-requisites\n\nEnsure\n[OpenTelemetry tracing is set-up](https://github.com/open-telemetry/opentelemetry-js/tree/main/api#trace-your-application)\nby ensuring:\n\n- The provider is registered\n- The monitored method is wrapped in the context of a parent span\n- A global context manager is set up\n\nSee [example set up](#basic-example) for a quick guide to getting the above\nsetup.\n\n#### Wrap all methods of a class in a span\n\n```typescript\nimport { Monitor } from \"@nifty-lil-tricks/monitoring\";\nimport { promisify } from \"node:util\";\n\n@Monitor()\nclass Service {\n  async hello(): Promise\u003cvoid\u003e {\n    // Do work\n    await promisify(setTimeout)(500);\n\n    // Do nested work\n    await this.nested();\n  }\n\n  async nested(): Promise\u003cvoid\u003e {\n    // Do work\n    await promisify(setTimeout)(1000);\n  }\n}\n```\n\n#### Filter allowed methods to monitor\n\nBy default, the monitor decorator monitors all\nnon-[private]((https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields))\nmethods. One can provide an `allowedMethods` option to filter the methods that\nare monitored. This filter can be provided in several types:\n\n- `string[]`\n- `RegExp`\n- `(methodName: string) =\u003e boolean`\n\n##### Filtering monitored methods by list of strings\n\n```typescript\nimport { Monitor } from \"@nifty-lil-tricks/monitoring\";\nimport { promisify } from \"node:util\";\n\n@Monitor({ allowedMethods: [\"allowed1\", \"allowed2\"] })\nclass Service {\n  // Not monitored\n  notAllowed(): void {}\n\n  // Monitored\n  allowed1(): void {}\n\n  // Monitored\n  allowed2(): void {}\n}\n```\n\n##### Filtering monitored methods by regex\n\n```typescript\nimport { Monitor } from \"@nifty-lil-tricks/monitoring\";\nimport { promisify } from \"node:util\";\n\n@Monitor({ allowedMethods: /^allowed.+/ })\nclass Service {\n  // Not monitored\n  notAllowed(): void {}\n\n  // Monitored\n  allowed1(): void {}\n\n  // Monitored\n  allowed2(): void {}\n}\n```\n\n##### Filtering monitored methods by function\n\n```typescript\nimport { Monitor } from \"@nifty-lil-tricks/monitoring\";\nimport { promisify } from \"node:util\";\n\n@Monitor({ allowedMethods: (method) =\u003e method.startsWith(\"allowed\") })\nclass Service {\n  // Not monitored\n  notAllowed(): void {}\n\n  // Monitored\n  allowed1(): void {}\n\n  // Monitored\n  allowed2(): void {}\n}\n```\n\n#### Override the default Span kind\n\nBy default, the monitor decorator sets the Span Kind to be `INTERNAL`. This\noption allows one to override this.\n\n```typescript\nimport { Monitor } from \"@nifty-lil-tricks/monitoring\";\nimport { promisify } from \"node:util\";\n\n@Monitor({ spanKind: SpanKind.SERVER })\nclass Service {\n  async hello(): Promise\u003cvoid\u003e {\n    // Do work\n    await promisify(setTimeout)(500);\n  }\n}\n```\n\n#### Override the inferred class name\n\nBy default, the monitor decorator infers the class name from the class. This\noption allows one to override this behaviour. A use-case for this would be when\none has multiple classes of the same name defined.\n\n```typescript\nimport { Monitor } from \"@nifty-lil-tricks/monitoring\";\nimport { promisify } from \"node:util\";\n\n@Monitor({ className: \"OtherService\" })\nclass Service {\n  async hello(): Promise\u003cvoid\u003e {\n    // Do work\n    await promisify(setTimeout)(500);\n  }\n}\n```\n\n#### Override the default tracer name\n\nBy default, the monitor decorator uses the default tracer to record spans. This\noption allows one to override this behaviour.\n\n```typescript\nimport { Monitor } from \"@nifty-lil-tricks/monitoring\";\nimport { promisify } from \"node:util\";\n\n@Monitor({ tracerName: \"some-other-tracer\" })\nclass Service {\n  async hello(): Promise\u003cvoid\u003e {\n    // Do work\n    await promisify(setTimeout)(500);\n  }\n}\n```\n\n#### Caveats\n\nPrivate methods\n[as defined here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields)\nare not monitoring by this decorator.\n\n```typescript\nimport { Monitor } from \"@nifty-lil-tricks/monitoring\";\nimport { promisify } from \"node:util\";\n\n@Monitor({ tracerName: \"some-other-tracer\" })\nclass Service {\n  // Monitored\n  async hello(): Promise\u003cvoid\u003e {\n    // Not monitored\n    await this.#privateMethod(())\n  }\n\n  async #privateMethod(): Promise\u003cvoid\u003e {\n    // Do work\n    await promisify(setTimeout)(500);\n  }\n}\n```\n\n## API\n\nThe API docs can be found\n[here](https://github.com/nifty-lil-tricks/monitoring/blob/main/docs/api/modules.md)\n\n## Examples\n\nExamples can be found\n[here](https://github.com/nifty-lil-tricks/monitoring/blob/main/examples).\n\n### Basic example\n\nTo run the `examples/basic.ts` example, run the following:\n\n- Ensure [Docker](https://www.docker.com/) is running\n- Start the Jaeger collector: `npm run start:collector`\n- Run the example: `npm run example:basic`\n- Navigate to the Jaeger UI: http://localhost:16686\n\n![Example exported trace](https://github.com/nifty-lil-tricks/monitoring/raw/main/docs/img/example-basic-export.png)\n\n### Nestjs example\n\nTo run the `examples/basic.ts` example, run the following:\n\n- Ensure [Docker](https://www.docker.com/) is running\n- Start the Jaeger collector: `npm run start:collector`\n- Run the example: `npm run example:nestjs`\n- Make a request to the app: `curl http://localhost:3000/`\n- Navigate to the Jaeger UI: http://localhost:16686\n\n![Example exported trace](https://github.com/nifty-lil-tricks/monitoring/raw/main/docs/img/example-nestjs-export.png)\n\n## Support\n\n| Platform Version | Supported          | Notes                                                     |\n| ---------------- | ------------------ | --------------------------------------------------------- |\n| Node.JS `v18`    | :white_check_mark: | TypeScript v5+ for typings                                |\n| Node.JS `v20`    | :white_check_mark: | TypeScript v5+ for typings                                |\n| Deno `v1`        | :x:                | Will be supported when OpenTelemetry is supported in Deno |\n| Web Browsers     | :x:                | Coming soon                                               |\n\n## Useful links\n\n- For more information on OpenTelemetry, visit: https://opentelemetry.io/\n- For more about OpenTelemetry JavaScript:\n  https://github.com/open-telemetry/opentelemetry-js\n- For help or feedback on this project, join us in\n  [GitHub Discussions](https://github.com/nifty-lil-tricks/monitoring/discussions)\n\n## License\n\nNifty li'l tricks packages are 100% free and open-source, under the\n[MIT license](https://github.com/nifty-lil-tricks/monitoring/blob/main/LICENSE).\n\nThis package is [Treeware](https://treeware.earth). If you use it in production,\nthen we ask that you\n[**buy the world a tree**](https://plant.treeware.earth/nifty-lil-tricks/monitoring)\nto thank us for our work. By contributing to the Treeware forest you’ll be\ncreating employment for local families and restoring wildlife habitats.\n\n## Contributions\n\n[Contributions](https://github.com/nifty-lil-tricks/monitoring/blob/main/CONTRIBUTING.md),\nissues and feature requests are very welcome. If you are using this package and\nfixed a bug for yourself, please consider submitting a PR!\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/nifty-lil-tricks/monitoring/graphs/contributors\"\u003e\n    \u003cimg src=\"https://contrib.rocks/image?repo=nifty-lil-tricks/monitoring\u0026columns=8\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnifty-lil-tricks%2Fmonitoring","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnifty-lil-tricks%2Fmonitoring","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnifty-lil-tricks%2Fmonitoring/lists"}