rian 0.2.2 → 0.2.4

package/index.d.ts

@@ -170,7 +170,7 @@ export interface Options {
 	 * If the id is malformed, the {@link create} method will throw an exception. If no root is
 	 * provided then one will be created obeying the {@link Options.sampler|sampling} rules.
 	 */
-	traceparent?: string;
+	traceparent?: string | null;
 }
 
 export const create: (name: string, options: Options) => Tracer;
@@ -181,9 +181,3 @@ export const create: (name: string, options: Options) => Tracer;
 export interface CallableScope extends Scope {
 	(cb: (scope: Omit<Scope, 'end'>) => void): ReturnType<typeof cb>;
 }
-
-/** @internal */
-export const PROMISES: WeakMap<Scope, Promise<any>[]>;
-
-/** @internal */
-export const ADD_PROMISE: (scope: Scope, promise: Promise<any>) => void;

package/index.js

@@ -1 +1 @@
-const e = require('tctx');const { measureFn:t } = require('rian/utils');var n=new WeakMap,a=(e,t)=>{n.has(e)?n.get(e).push(t):n.set(e,[t])},r=(t,n)=>!n||e.is_sampled(n),o={"telemetry.sdk.name":"rian","telemetry.sdk.version":"0.2.2"},s=(a,s)=>{let i=new Set,p=s.sampler||r,d="boolean"!=typeof p,c=(n,a)=>{let r=d?p(n,a,s.context):p,o=a?a.child(r):e.make(r),m={id:o,parent:a,start:Date.now(),name:n,events:[],context:{}};r&&i.add(m);let l=e=>t(l,e);return l.traceparent=o,l.fork=e=>c(e,o),l.set_context=e=>{"function"!=typeof e?Object.assign(m.context,e):m.context=e(m.context)},l.add_event=(e,t)=>{m.events.push({name:e,timestamp:Date.now(),attributes:t||{}})},l.end=()=>{null==m.end&&(m.end=Date.now())},l},m=c(a,"string"==typeof s.traceparent?e.parse(s.traceparent):void 0),l=m.end.bind(m);return m.end=async()=>(l(),n.has(m)&&await Promise.all(n.get(m)),s.exporter(i,{...s.context||{},...o})),m};exports.ADD_PROMISE=a;exports.PROMISES=n;exports.create=s;
+const { measureFn:e } = require('rian/utils');const t = require('tctx');var n=(e,n)=>!n||t.is_sampled(n),a={"telemetry.sdk.name":"rian","telemetry.sdk.version":"0.2.4"},r=(r,o)=>{let s=new Set,d=new Set,i=o.sampler||n,p="boolean"!=typeof i,m=(n,a)=>{let r=p?i(n,a,o.context):i,c=a?a.child(r):t.make(r),l={id:c,parent:a,start:Date.now(),name:n,events:[],context:{}};r&&s.add(l);let x=t=>e(x,t);return x.traceparent=c,x.fork=e=>m(e,c),x.set_context=e=>{"function"!=typeof e?Object.assign(l.context,e):l.context=e(l.context)},x.add_event=(e,t)=>{l.events.push({name:e,timestamp:Date.now(),attributes:t||{}})},x.end=()=>{null==l.end&&(l.end=Date.now())},x.__add_promise=d.add.bind(d),x},c=m(r,"string"==typeof o.traceparent?t.parse(o.traceparent):void 0),l=c.end.bind(c);return c.end=async()=>(l(),d.size>0&&await Promise.all([...d.values()]),o.exporter(s,{...o.context||{},...a})),c};exports.create=r;

package/index.mjs

@@ -1 +1 @@
-import*as e from"tctx";import{measureFn as t}from"rian/utils";var n=new WeakMap,a=(e,t)=>{n.has(e)?n.get(e).push(t):n.set(e,[t])},r=(t,n)=>!n||e.is_sampled(n),o={"telemetry.sdk.name":"rian","telemetry.sdk.version":"0.2.2"},s=(a,s)=>{let i=new Set,p=s.sampler||r,d="boolean"!=typeof p,c=(n,a)=>{let r=d?p(n,a,s.context):p,o=a?a.child(r):e.make(r),m={id:o,parent:a,start:Date.now(),name:n,events:[],context:{}};r&&i.add(m);let l=e=>t(l,e);return l.traceparent=o,l.fork=e=>c(e,o),l.set_context=e=>{"function"!=typeof e?Object.assign(m.context,e):m.context=e(m.context)},l.add_event=(e,t)=>{m.events.push({name:e,timestamp:Date.now(),attributes:t||{}})},l.end=()=>{null==m.end&&(m.end=Date.now())},l},m=c(a,"string"==typeof s.traceparent?e.parse(s.traceparent):void 0),l=m.end.bind(m);return m.end=async()=>(l(),n.has(m)&&await Promise.all(n.get(m)),s.exporter(i,{...s.context||{},...o})),m};export{a as ADD_PROMISE,n as PROMISES,s as create};
+import{measureFn as e}from"rian/utils";import*as t from"tctx";var n=(e,n)=>!n||t.is_sampled(n),a={"telemetry.sdk.name":"rian","telemetry.sdk.version":"0.2.4"},r=(r,o)=>{let s=new Set,d=new Set,i=o.sampler||n,p="boolean"!=typeof i,m=(n,a)=>{let r=p?i(n,a,o.context):i,c=a?a.child(r):t.make(r),l={id:c,parent:a,start:Date.now(),name:n,events:[],context:{}};r&&s.add(l);let x=t=>e(x,t);return x.traceparent=c,x.fork=e=>m(e,c),x.set_context=e=>{"function"!=typeof e?Object.assign(l.context,e):l.context=e(l.context)},x.add_event=(e,t)=>{l.events.push({name:e,timestamp:Date.now(),attributes:t||{}})},x.end=()=>{null==l.end&&(l.end=Date.now())},x.__add_promise=d.add.bind(d),x},c=m(r,"string"==typeof o.traceparent?t.parse(o.traceparent):void 0),l=c.end.bind(c);return c.end=async()=>(l(),d.size>0&&await Promise.all([...d.values()]),o.exporter(s,{...o.context||{},...a})),c};export{r as create};

package/license

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Marais Rossouw <me@marais.dev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rian",
-	"version": "0.2.2",
+	"version": "0.2.4",
 	"description": "Effective tracing for the edge and origins",
 	"keywords": [
 		"opentelemetry",
@@ -17,13 +17,8 @@
 	],
 	"repository": "maraisr/rian",
 	"license": "MIT",
-	"author": {
-		"name": "Marais Rossouw",
-		"email": "me@marais.dev",
-		"url": "https://marais.io"
-	},
+	"author": "Marais Rossow <me@marais.dev> (https://marais.io)",
 	"sideEffects": false,
-	"type": "module",
 	"exports": {
 		".": {
 			"types": "./index.d.ts",
@@ -58,13 +53,29 @@
 		"utils/*"
 	],
 	"scripts": {
-		"build": "bundt --minify"
+		"bench": "node -r tsm bench/index.ts",
+		"build": "bundt --minify",
+		"format": "prettier --write \"{*,{src,test}/**/*,examples/*/**,bench/*,.github/**/*}.+(ts|js|json|yml|md)\"",
+		"pretest": "pnpm run build",
+		"test": "uvu -r tsm test \".spec.m?ts$\"",
+		"typecheck": "tsc --noEmit --skipLibCheck"
 	},
 	"dependencies": {
 		"flattie": "^1.1.0",
 		"tctx": "^0.0.10"
 	},
 	"devDependencies": {
-		"bundt": "2.0.0-next.5"
+		"@marais/prettier": "0.0.1",
+		"@marais/tsconfig": "0.0.3",
+		"bundt": "2.0.0-next.5",
+		"nanospy": "0.5.0",
+		"prettier": "2.7.1",
+		"tsm": "2.2.2",
+		"typescript": "4.8.4",
+		"uvu": "0.5.6"
+	},
+	"prettier": "@marais/prettier",
+	"volta": {
+		"node": "17.2.0"
 	}
 }

package/readme.md

@@ -0,0 +1,278 @@
+<div align="right">
+<img src="files/logo-light.svg#gh-light-mode-only" alt="rian light mode logo" width="200px">
+<img src="files/logo-dark.svg#gh-dark-mode-only" alt="rian dark mode logo" width="200px">
+<br />
+<br />
+
+<p><code>npm add rian</code> doesn't overcomplicate tracing</p>
+<span>
+<a href="https://github.com/maraisr/rian/actions/workflows/ci.yml">
+	<img src="https://github.com/maraisr/rian/actions/workflows/ci.yml/badge.svg"/>
+</a>
+<a href="https://npm-stat.com/charts.html?package=rian">
+	<img src="https://badgen.net/npm/dw/rian?labelColor=black&color=black&cache=600" alt="downloads"/>
+</a>
+<a href="https://packagephobia.com/result?p=rian">
+	<img src="https://badgen.net/packagephobia/install/rian?labelColor=black&color=black" alt="size"/>
+</a>
+<a href="https://bundlephobia.com/result?p=rian">
+	<img src="https://badgen.net/bundlephobia/minzip/rian?labelColor=black&color=black" alt="size"/>
+</a>
+</span>
+
+<br />
+<br />
+</div>
+
+## ⚡ Features
+
+- 🤔 **Familiar** — looks very much like OpenTracing.
+
+- ✅ **Simple** — `create` a tracer, and `.end()` a tracer, done.
+
+- 🏎 **Performant** — check the [benchmarks](#-benchmark).
+
+- 🪶 **Lightweight** — a mere 1Kb and next to no [dependencies](https://npm.anvaka.com/#/view/2d/rian/).
+
+## 🚀 Usage
+
+> Visit [/examples](/examples) for more info!
+
+```ts
+import { create } from 'rian';
+import { measure } from 'rian/utils';
+import { exporter } from 'rian/exporter.otel.http';
+
+// ~> Where to send the spans.
+const otel_endpoint = exporter((payload) =>
+  fetch('/traces/otlp', {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  }),
+);
+
+// ~> Create a tracer — typically "per request" or "per operation"
+const tracer = create('GET ~> /data', {
+  exporter: otel_endpoint,
+});
+
+// Let us trace
+
+tracer.set_context({
+  user: request_context.user_id,
+});
+
+// ~> Wrap any method and be timed 🕺🏻
+const data = await measure(tracer.fork('db::read'), get_data);
+
+// ~> Maybe have some in-flow spanning
+const span = tracer.span('process records');
+
+for (let row of data) {
+  span.add_event('doing stuff', { id: row.id });
+  do_stuff(row);
+}
+
+span.end();
+
+// ~> And finally let's export — will also end the root span.
+await tracer.end();
+
+/*
+And we end up with something like this in our reporting tool:
+
+[ GET ~> /data .................................... (1.2ms) ]
+   [ db::read .... (0.5ms) ]
+                           [ process records .... (0.5ms) ]
+ */
+```
+
+## 🔎 API
+
+#### Module: [`rian`](./packages/rian/src/index.ts)
+
+The main and _default_ module responsible for creating and provisioning spans.
+
+> 💡 Note ~> when providing span context values, please stick to
+> [Semantic Conventions](https://github.com/opentracing/specification/blob/master/semantic_conventions.md), but won't be
+> enforced.
+
+#### Module: [`rian/exporter.zipkin`](./packages/rian/src/exporter.zipkin.ts)
+
+Exports the spans created using the zipkin protocol and leaves the shipping up to you.
+
+> 💡 Note ~> with the nature of zipkin, the `localEndpoint` must be set in your span context.
+>
+> <details><summary>Example</summary>
+>
+> ```ts
+> const tracer = create('example', {
+>   context: {
+>     localEndpoint: {
+>       serviceName: 'my-service', // 👈 important part
+>     },
+>   },
+> });
+> ```
+>
+> Both of these are functionally equivalent. `service.name` will be used if no `localEndpoint.serviceName` is set.
+>
+> ```ts
+> const tracer = create('example', {
+>   context: {
+>     'service.name': 'my-service',
+>   },
+> });
+> ```
+>
+> </details>
+
+#### Module: [`rian/exporter.otel.http`](./packages/rian/src/exporter.otel.http.ts)
+
+Implements the OpenTelemetry protocol for use with http transports.
+
+> 💡 Note ~> services require a `service.name` context value.
+>
+> <details><summary>Example</summary>
+>
+> ```ts
+> const tracer = create('example', {
+>   context: {
+>     'service.name': 'my-service', // 👈 important part
+>   },
+> });
+> ```
+>
+> </details>
+
+## 🧑‍🍳 Exporter Recipes
+
+<details><summary>NewRelic</summary>
+
+```ts
+import { create } from 'rian';
+import { exporter } from 'rian/exporter.zipkin';
+
+const newrelic = exporter((payload) =>
+  fetch('https://trace-api.newrelic.com/trace/v1', {
+    method: 'POST',
+    headers: {
+      'api-key': '<your api key>',
+      'content-type': 'application/json',
+      'data-format': 'zipkin',
+      'data-format-version': '2',
+    },
+    body: JSON.stringify(payload),
+  }),
+);
+
+const tracer = create('example', {
+  context: {
+    'service.name': 'my-service', // 👈 important part
+  },
+  exporter: newrelic,
+});
+```
+
+[learn more](https://docs.newrelic.com/docs/distributed-tracing/trace-api/introduction-trace-api/)
+
+</details>
+
+<details><summary>LightStep</summary>
+
+```ts
+import { create } from 'rian';
+import { exporter } from 'rian/exporter.otel.http';
+
+const lightstep = exporter((payload) =>
+  fetch('https://ingest.lightstep.com/traces/otlp/v0.6', {
+    method: 'POST',
+    headers: {
+      'lightstep-access-token': '<your api key>',
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(payload),
+  }),
+);
+
+const tracer = create('example', {
+  context: {
+    'service.name': 'my-service', // 👈 important part
+  },
+  exporter: lightstep,
+});
+```
+
+[learn more](https://opentelemetry.lightstep.com/tracing/)
+
+</details>
+
+## 🤔 Motivation
+
+Firstly, what is `rian`? _trace_ in Irish is `rian`.
+
+In efforts to be better observant citizens, we generally reach for the — NewRelic, LightStep, DataDog's. Which, and in
+no offence to them, is bloated and slow! Where they more often than not do way too much or and relatively speaking, ship
+useless traces. Which ramp up your bill — see... every span you trace, costs.
+
+And here we are, introducing **rian** — a lightweight, fast effective tracer. Inspired by the giants in the industry,
+OpenTracing and OpenTelemetry.
+
+You might have not heard of those before — and that is okay. It means the design goals from OpenTelemetry or OpenTracing
+has been met. They are frameworks built to abstract the telemetry part from vendors. So folk like NewRelic can wrap
+their layers on top of open telemetry — and have libraries instrument theirs without knowing about the vendor. Which
+allows consumers to ship those spans to the vendor of their choosing. OpenTracing has a very similar design goal, so
+please do go checkout their documentation's, to help decide.
+
+Rian does not intend to align or compete with them. rian's intent is to be used to instrument your application and
+**only** your application. Rian is primed in that critical business paths — where you don't care " which handlers
+MongoDB ran", or how many network calls your ORM made. Cardinality will destroy you. Although rian can scale to support
+those as well. But the reality is; there are profiler tools far more capable — "right tool for the job".
+
+Rian is simply a tracer you can use to see what your application is doing, have better insight into why something failed
+and stitch it with your logs. It starts by capturing a [`w3c trace-context`](https://www.w3.org/TR/trace-context/),
+tracing some business steps. "inbound request /data", "getting data", "sending email", or as granular as you'd like. And
+have that forwarded onto all sub-services.
+
+You see, the primary design goal is targeted at edge or service workers — where lean quick tracers is favoured.
+
+Rian is still in active development, but ready for production!
+
+## 💨 Benchmark
+
+> via the [`/bench`](/bench) directory with Node v17.2.0
+
+```
+Validation :: single span
+✔ rian
+✔ opentelemetry
+✔ opentracing
+
+Benchmark :: single span
+  rian                   x 137,181 ops/sec ±2.82% (82 runs sampled)
+  opentelemetry          x 114,197 ops/sec ±11.37% (75 runs sampled)
+  opentracing            x  33,363 ops/sec ±1.27% (89 runs sampled)
+
+Validation :: child span
+✔ rian
+✔ opentelemetry
+✔ opentracing
+
+Benchmark :: child span
+  rian                   x 75,567 ops/sec ±7.95% (77 runs sampled)
+  opentelemetry          x 65,618 ops/sec ±8.45% (82 runs sampled)
+  opentracing            x 15,452 ops/sec ±15.35% (77 runs sampled)
+
+```
+
+> And please... I know these results are anything but the full story. But it's a number and point on comparison.
+
+## License
+
+MIT © [Marais Rossouw](https://marais.io)
+
+##### Disclaimer
+
+<sup>- NewRelic is a registered trademark of https://newrelic.com/ and not affiliated with this project.</sup><br />
+<sup>- DataDog is a registered trademark of https://www.datadoghq.com/ and not affiliated with this project.</sup><br />
+<sup>- LightStep is a registered trademark of https://lightstep.com/ and not affiliated with this project.</sup>

package/utils/index.js

@@ -1 +1 @@
-const { ADD_PROMISE:r, PROMISES:t } = require('rian');var n=(n,o,...e)=>{try{var a=o(...e,n),c=a instanceof Promise;return c&&!t.has(n)&&r(n,a.catch((r=>{n.set_context({error:r})})).finally((()=>n.end()))),a}catch(r){throw r instanceof Error&&n.set_context({error:r}),r}finally{!0!==c&&n.end()}},o=(r,t,o,...e)=>n(r.fork(t),o,...e),e=(r,t,o)=>function(){return n(r.fork(t),o,...arguments)};exports.measure=o;exports.measureFn=n;exports.wrap=e;
+var r=(r,t,...e)=>{try{var n=t(...e,r),o=n instanceof Promise;return o&&r.__add_promise(n.catch((t=>{r.set_context({error:t})})).finally((()=>r.end()))),n}catch(t){throw t instanceof Error&&r.set_context({error:t}),t}finally{!0!==o&&r.end()}},t=(t,e,n,...o)=>r(t.fork(e),n,...o),e=(t,e,n)=>function(){return r(t.fork(e),n,...arguments)};exports.measure=t;exports.measureFn=r;exports.wrap=e;

package/utils/index.mjs

@@ -1 +1 @@
-import{ADD_PROMISE as r,PROMISES as t}from"rian";var n=(n,o,...e)=>{try{var a=o(...e,n),c=a instanceof Promise;return c&&!t.has(n)&&r(n,a.catch((r=>{n.set_context({error:r})})).finally((()=>n.end()))),a}catch(r){throw r instanceof Error&&n.set_context({error:r}),r}finally{!0!==c&&n.end()}},o=(r,t,o,...e)=>n(r.fork(t),o,...e),e=(r,t,o)=>function(){return n(r.fork(t),o,...arguments)};export{o as measure,n as measureFn,e as wrap};
+var r=(r,t,...e)=>{try{var n=t(...e,r),o=n instanceof Promise;return o&&r.__add_promise(n.catch((t=>{r.set_context({error:t})})).finally((()=>r.end()))),n}catch(t){throw t instanceof Error&&r.set_context({error:t}),t}finally{!0!==o&&r.end()}},t=(t,e,n,...o)=>r(t.fork(e),n,...o),e=(t,e,n)=>function(){return r(t.fork(e),n,...arguments)};export{t as measure,r as measureFn,e as wrap};