rian 0.3.0-next.1 → 0.3.0-next.11

package/async.d.ts

@@ -0,0 +1,59 @@
+import type { CallableScope, Options, Scope } from 'rian';
+
+export { report, configure } from 'rian';
+
+/**
+ * Returns the current span in the current execution context.
+ *
+ * This will throw an error if there is no current span.
+ *
+ * @example
+ *
+ * ```ts
+ * function doWork() {
+ *   const span = currentSpan();
+ *   span.set_context({ foo: 'bar' });
+ * }
+ *
+ * span('some-name')(() => {
+ *   doWork(); // will guarantee `currentSpan` returns this span
+ * });
+ * ```
+ */
+export function currentSpan(): Scope;
+
+/**
+ * Creates a new span for the currently active tracer.
+ *
+ * @example
+ *
+ * ```ts
+ * tracer('some-name')(() => {
+ *    // some deeply nested moments later
+ *    const s = span('my-span');
+ * });
+ * ```
+ */
+export function span(name: string): CallableScope;
+
+export type Tracer<T> = (cb: T) => ReturnType<T>;
+
+/**
+ * A tracer is a logical unit in your application. This alleviates the need to pass around a tracer instance.
+ *
+ * All spans produced by a tracer will all collect into a single span collection that is given to {@link report}.
+ *
+ * @example
+ *
+ * ```ts
+ * const trace = tracer('server');
+ *
+ * trace(() => {
+ *  // application logic
+ * });
+ * ```
+ */
+export function tracer<T extends () => any>(
+	name: string,
+	options?: Options,
+): Tracer<T>;

package/async.js

@@ -0,0 +1 @@
+const e = require('node:async_hooks');const { measure:t } = require('rian/utils');const { make:n, parse:r, SAMPLED_FLAG:o } = require('tctx');const { is_sampled:a } = require('tctx');var s={};function c(e,t={}){s={...t,"service.name":e,"telemetry.sdk.name":"rian","telemetry.sdk.version":"0.3.0-next.11"}}var l=new Set,i=new WeakMap;async function p(e){let t=[],n=new Map;for(let[e,r]of l){let o;n.has(r)?o=n.get(r).spans:n.set(r,{scope:r,spans:o=[]}),o.push(e),i.has(r)&&(t.push(...i.get(r)),i.delete(r))}return l.clear(),t.length&&await Promise.all(t),e({resource:s,scopeSpans:n.values()})}function u(e,t){return a(t)}var d=new e.AsyncLocalStorage;function m(){let e=d.getStore()?.[1];if(null==e)throw new Error("no current span");return e}function f(e){let r=d.getStore();if(!r)throw Error("TODO");let o=r[0],a=o.scope,s=r[1],c=o.sampler,p=s?.traceparent??o.root_id,u=p?p.child():n(),m="boolean"!=typeof c?c(e,u,a):c;u.flags;let w={id:u,parent:p,start:o.clock.now(),name:e,events:[],context:{}};m&&l.add([w,a]);let g=e=>d.run([o,g],t,g,e);g.traceparent=u,g.span=f,g.set_context=e=>{"function"!=typeof e?Object.assign(w.context,e):w.context=e(w.context)},g.add_event=(e,t)=>{w.events.push({name:e,timestamp:o.clock.now(),attributes:t||{}})},g.end=()=>{null==w.end&&(w.end=o.clock.now())};let h=i.get(a);return g.__add_promise=e=>{h.add(e),e.then((()=>h.delete(e)))},g}function w(e,t){let n=t?.sampler??u,o={name:e},a={root_id:"string"==typeof t?.traceparent?r(t.traceparent):void 0,scope:o,sampler:n,clock:t?.clock??Date};return i.set(o,new Set),function(e){let t=d.getStore();return a.root_id||(a.root_id=t?.[0].root_id),d.run([a,t?.[1]||null],e)}}exports.configure=c;exports.currentSpan=m;exports.report=p;exports.span=f;exports.tracer=w;

package/async.mjs

@@ -0,0 +1 @@
+import*as e from"node:async_hooks";import{measure as t}from"rian/utils";import{make as n,parse as r,SAMPLED_FLAG as o}from"tctx";import{is_sampled as a}from"tctx";var s={};function c(e,t={}){s={...t,"service.name":e,"telemetry.sdk.name":"rian","telemetry.sdk.version":"0.3.0-next.11"}}var l=new Set,i=new WeakMap;async function p(e){let t=[],n=new Map;for(let[e,r]of l){let o;n.has(r)?o=n.get(r).spans:n.set(r,{scope:r,spans:o=[]}),o.push(e),i.has(r)&&(t.push(...i.get(r)),i.delete(r))}return l.clear(),t.length&&await Promise.all(t),e({resource:s,scopeSpans:n.values()})}function u(e,t){return a(t)}var d=new e.AsyncLocalStorage;function m(){let e=d.getStore()?.[1];if(null==e)throw new Error("no current span");return e}function f(e){let r=d.getStore();if(!r)throw Error("TODO");let o=r[0],a=o.scope,s=r[1],c=o.sampler,p=s?.traceparent??o.root_id,u=p?p.child():n(),m="boolean"!=typeof c?c(e,u,a):c;u.flags;let w={id:u,parent:p,start:o.clock.now(),name:e,events:[],context:{}};m&&l.add([w,a]);let g=e=>d.run([o,g],t,g,e);g.traceparent=u,g.span=f,g.set_context=e=>{"function"!=typeof e?Object.assign(w.context,e):w.context=e(w.context)},g.add_event=(e,t)=>{w.events.push({name:e,timestamp:o.clock.now(),attributes:t||{}})},g.end=()=>{null==w.end&&(w.end=o.clock.now())};let h=i.get(a);return g.__add_promise=e=>{h.add(e),e.then((()=>h.delete(e)))},g}function w(e,t){let n=t?.sampler??u,o={name:e},a={root_id:"string"==typeof t?.traceparent?r(t.traceparent):void 0,scope:o,sampler:n,clock:t?.clock??Date};return i.set(o,new Set),function(e){let t=d.getStore();return a.root_id||(a.root_id=t?.[0].root_id),d.run([a,t?.[1]||null],e)}}export{c as configure,m as currentSpan,p as report,f as span,w as tracer};

package/exporter.otel.http.js

@@ -0,0 +1 @@
+var e=r=>{let a=typeof r,s={};return"string"===a?s.stringValue=r:"number"===a?Number.isInteger(r)?s.intValue=r:s.doubleValue=r:"boolean"===a?s.boolValue=r:Array.isArray(r)?s.arrayValue={values:r.map((t=>e(t)))}:r&&(s.kvlistValue={values:t(r)}),s},t=t=>{let r=[];for(let a of Object.keys(t))r.push({key:a,value:e(t[a])});return r},r=e=>{switch(e){default:case"INTERNAL":return 1;case"SERVER":return 2;case"CLIENT":return 3;case"PRODUCER":return 4;case"CONSUMER":return 5}},a=e=>a=>{let s=[];for(let e of a.scopeSpans){let a=[];s.push({scope:e.scope,spans:a});for(let s of e.spans){let e,{kind:n,error:u,...o}=s.context;u&&(e={code:2},"message"in u&&(e.message=u.message)),a.push({traceId:s.id.trace_id,spanId:s.id.parent_id,parentSpanId:s.parent?.parent_id,name:s.name,kind:r(n||"INTERNAL"),startTimeUnixNano:1e6*s.start,endTimeUnixNano:s.end?1e6*s.end:void 0,droppedAttributesCount:0,droppedEventsCount:0,droppedLinksCount:0,attributes:t(o),status:e||{code:0},events:s.events.map((e=>({name:e.name,attributes:t(e.attributes),droppedAttributesCount:0,timeUnixNano:1e6*e.timestamp})))})}}return e({resourceSpans:[{resource:{attributes:t(a.resource),droppedAttributesCount:0},scopeSpans:s}]})};exports.exporter=a;

package/exporter.otel.http.mjs

@@ -0,0 +1 @@
+var e=r=>{let a=typeof r,s={};return"string"===a?s.stringValue=r:"number"===a?Number.isInteger(r)?s.intValue=r:s.doubleValue=r:"boolean"===a?s.boolValue=r:Array.isArray(r)?s.arrayValue={values:r.map((t=>e(t)))}:r&&(s.kvlistValue={values:t(r)}),s},t=t=>{let r=[];for(let a of Object.keys(t))r.push({key:a,value:e(t[a])});return r},r=e=>{switch(e){default:case"INTERNAL":return 1;case"SERVER":return 2;case"CLIENT":return 3;case"PRODUCER":return 4;case"CONSUMER":return 5}},a=e=>a=>{let s=[];for(let e of a.scopeSpans){let a=[];s.push({scope:e.scope,spans:a});for(let s of e.spans){let e,{kind:n,error:u,...o}=s.context;u&&(e={code:2},"message"in u&&(e.message=u.message)),a.push({traceId:s.id.trace_id,spanId:s.id.parent_id,parentSpanId:s.parent?.parent_id,name:s.name,kind:r(n||"INTERNAL"),startTimeUnixNano:1e6*s.start,endTimeUnixNano:s.end?1e6*s.end:void 0,droppedAttributesCount:0,droppedEventsCount:0,droppedLinksCount:0,attributes:t(o),status:e||{code:0},events:s.events.map((e=>({name:e.name,attributes:t(e.attributes),droppedAttributesCount:0,timeUnixNano:1e6*e.timestamp})))})}}return e({resourceSpans:[{resource:{attributes:t(a.resource),droppedAttributesCount:0},scopeSpans:s}]})};export{a as exporter};

package/exporter.zipkin.js

@@ -0,0 +1 @@
+const { flattie:e } = require('flattie');var t=t=>a=>{let r=[];for(let t of a.scopeSpans)for(let n of t.spans){let{kind:s,error:i,...o}=n.context;i&&(o.error=!("message"in i)||{name:i.name,message:i.message,stack:i.stack}),r.push({id:n.id.parent_id,traceId:n.id.trace_id,parentId:n.parent?n.parent.parent_id:void 0,name:n.name,kind:"INTERNAL"===s?void 0:s,timestamp:1e3*n.start,duration:n.end?1e3*(n.end-n.start):void 0,localEndpoint:{serviceName:`${a.resource["service.name"]}@${t.scope.name}`},tags:e({...a.resource,...o},".",!0),annotations:n.events.map((e=>({value:`${e.name} :: ${JSON.stringify(e.attributes)}`,timestamp:1e3*e.timestamp})))})}return t(r)};exports.exporter=t;

package/exporter.zipkin.mjs

@@ -0,0 +1 @@
+import{flattie as e}from"flattie";var t=t=>a=>{let r=[];for(let t of a.scopeSpans)for(let n of t.spans){let{kind:s,error:i,...o}=n.context;i&&(o.error=!("message"in i)||{name:i.name,message:i.message,stack:i.stack}),r.push({id:n.id.parent_id,traceId:n.id.trace_id,parentId:n.parent?n.parent.parent_id:void 0,name:n.name,kind:"INTERNAL"===s?void 0:s,timestamp:1e3*n.start,duration:n.end?1e3*(n.end-n.start):void 0,localEndpoint:{serviceName:`${a.resource["service.name"]}@${t.scope.name}`},tags:e({...a.resource,...o},".",!0),annotations:n.events.map((e=>({value:`${e.name} :: ${JSON.stringify(e.attributes)}`,timestamp:1e3*e.timestamp})))})}return t(r)};export{t as exporter};

package/index.d.ts

@@ -1,31 +1,91 @@
 import type { Traceparent } from 'tctx';
 
+// --- tracer
+
+/**
+ * The exporter is called when the {@link report} method is called.
+ */
+export type Exporter = (trace: {
+	resource: Context;
+	scopeSpans: IterableIterator<ScopedSpans>;
+}) => any;
+
+export type ScopedSpans = {
+	readonly scope: { readonly name: string };
+	readonly spans: ReadonlyArray<Readonly<Span>>;
+};
+
+export type Options = {
+	/**
+	 * @borrows {@link Sampler}
+	 */
+	sampler?: Sampler | boolean;
+
+	/**
+	 * A root, or extracted w3c traceparent string header.
+	 *
+	 * 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 on each span.
+	 */
+	traceparent?: string | null;
+
+	clock?: ClockLike;
+};
+
+export type Tracer = Pick<Scope, 'span'>;
+
+/**
+ * @borrows {@link Span.context}
+ */
+export type Context = {
+	[property: string]: any;
+};
+
+/**
+ * Allows a sampling decision to be made. This method will influence the {@link Span.id|traceparent} sampling flag.
+ *
+ * Return true if the span should be sampled, and reported to the {@link Exporter}.
+ * Return false if the span should not be sampled, and not reported to the {@link Exporter}.
+ */
+export type Sampler = (
+	/**
+	 * The name of the span.
+	 */
+	readonly name: string,
+	/**
+	 * The traceparent id of the span.
+	 */
+	readonly id: Traceparent,
+	/**
+	 * The tracer this span belongs to.
+	 */
+	readonly tracer: { readonly name: string },
+) => boolean;
+
+// --- spans
+
 /**
  * Spans are units within a distributed trace. Spans encapsulate mainly 3 pieces of information, a
  * {@link Span.name|name}, and a {@link Span.start|start} and {@link Span.end|end} time.
  *
  * Each span should be named, not too vague, and not too precise. For example, "resolve_user_ids"
- * and not "resolver_user_ids[1,2,3]" nor "resolve".
+ * and not "resolver_user_ids[1,2,3]" nor "resolver".
  *
  * A span forms part of a wider trace, and can be visualized like:
  *
  * ```plain
  *  [Span A················································(2ms)]
  *    [Span B·········································(1.7ms)]
- *       [Span D···············(0.8ms)]  [Span C......(0.6ms)]
+ *       [Span D···············(0.8ms)] [Span C......(0.6ms)]
  * ```
- *
- * ---
- *
- * Spans are aimed to interoperate with
- * {@link https://github.com/opentracing/specification/blob/master/specification.md|OpenTracing's Spans}, albeit not entirely api compatible — they do share principles.
  */
-export interface Span {
+export type Span = {
 	/**
 	 * A human-readable name for this span. For example the function name, the name of a subtask,
 	 * or stage of the larger stack.
 	 *
 	 * @example
+	 *
 	 * "resolve_user_ids"
 	 * "[POST] /api"
 	 */
@@ -49,7 +109,7 @@ export interface Span {
 	/**
 	 * The time represented as a UNIX epoch timestamp in milliseconds when this span was created.
 	 * Typically, via
-	 * {@link Scope.fork|tracer.fork()}.
+	 * {@link Scope.span|scope.span()}.
 	 */
 	start: number;
 
@@ -63,7 +123,7 @@ export interface Span {
 	 * An arbitrary context object useful for storing information during a trace.
 	 *
 	 * Usually following a convention such as `tag.*`, `http.*` or any of the
-	 * {@link https://github.com/opentracing/specification/blob/master/semantic_conventions.md|Semantic Conventions outlined by OpenTracing}.
+	 * {@link https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/|OpenTelemetry Trace Semantic Conventions}.
 	 *
 	 * ### Note!
 	 *
@@ -84,9 +144,11 @@ export interface Span {
 	 * new span.
 	 */
 	events: { name: string; timestamp: number; attributes: Context }[];
-}
+};
 
-export interface Scope {
+// --- scopes
+
+export type Scope = {
 	/**
 	 * A W3C traceparent. One can .toString() this if you want to cross a network.
 	 */
@@ -95,7 +157,12 @@ export interface Scope {
 	/**
 	 * Forks the span into a new child span.
 	 */
-	span(name: string): CallableScope;
+	span(
+		/**
+		 * @borrows {@link Span.name}
+		 */
+		name: string,
+	): CallableScope;
 
 	/**
 	 * Allows the span's context to be set. Passing an object will be `Object.assign`ed into the
@@ -116,70 +183,67 @@ export interface Scope {
 	 * timestamp nulled out — when the tracer ends.
 	 */
 	end(): void;
-}
+};
+
+export type CallableScope = Scope & {
+	<Fn extends (scope: Omit<Scope, 'end'>) => any>(cb: Fn): ReturnType<Fn>;
+};
 
-export interface Tracer extends Pick<Scope, 'span'> {
-	report(): ReturnType<Exporter>;
-}
+// --- main api
 
 /**
- * An exporter is a method called when the parent scope ends, gets given a Set of all spans traced
- * during this execution.
+ * A tracer is a logical unit in your application. This alleviates the need to pass around a tracer instance.
+ *
+ * All spans produced by a tracer will all collect into a single span collection that is given to {@link report}.
+ *
+ * @example
+ *
+ * ```ts
+ * // file: server.ts
+ * const trace = tracer('server');
+ *
+ * // file: orm.ts
+ * const trace = tracer('orm');
+ *
+ * // file: api.ts
+ * const trace = tracer('api');
+ * ```
  */
-export type Exporter = (
-	spans: ReadonlySet<Readonly<Span>>,
-	context: Context,
-) => any;
+export function tracer(name: string, options?: Options): Tracer;
+
+// -- general api
 
 /**
- * @borrows {@link Span.context}
+ * Awaits all active promises, and then calls the {@link Options.exporter|exporter}. Passing all collected spans.
  */
-export interface Context {
-	[property: string]: any;
-}
+export async function report<T extends Exporter>(
+	exporter: T,
+): Promise<ReturnType<T>>;
 
 /**
- * Should return true when you want to sample the span, this is ran before the span is traced — so
- * decisions is made preemptively.
+ * Calling this method will set the resource attributes for this runtime. This is useful for things like:
+ * - setting the deployment environment of the application
+ * - setting the k8s namespace
+ * - ...
  *
- * The Span itself will still be included in the {@link Options.exporter|exporter}, and can be
- * filtered out there.
+ * The `name` argument will set the `service.name` attribute. And is required.
  *
- * Sampling does impact the traceparent, for injection — and is encoded there.
+ * The fields can be whatever you want, but it is recommended to follow the {@link https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/|OpenTelemetry Resource Semantic Conventions}.
+ *
+ * @example
+ *
+ * ```ts
+ * configure('my-service', { 'deployment.environment': 'production', 'k8s.namespace.name': 'default' });
+ * ```
  */
-export type Sampler = (
-	name: string,
-	parentId?: Traceparent,
-	context?: Context,
-) => boolean;
-
-export interface Options {
-	/**
-	 * @borrows {@link Exporter}
-	 */
-	exporter: Exporter;
-
-	/**
-	 * @borrows {@link Sampler}
-	 */
-	sampler?: Sampler | boolean;
-
-	context?: Context;
+export function configure(name: string, attributes: Context = {}): void;
 
+/**
+ * Provinding a clock allows you to control the time of the span.
+ */
+export type ClockLike = {
 	/**
-	 * A root, or extracted w3c traceparent stringed header.
-	 *
-	 * 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.
+	 * Must return the number of milliseconds since the epoch.
 	 */
-	traceparent?: string | null;
-}
-
-export const create: (name: string, options: Options) => Tracer;
-
-// ==> internals
-
-/** @internal */
-export interface CallableScope extends Scope {
-	(cb: (scope: Omit<Scope, 'end'>) => void): ReturnType<typeof cb>;
-}
+	now(): number;
+};

package/index.js

@@ -1 +1 @@
-const { measureFn:e } = require('rian/utils');const t = require('tctx');var n=(e,n)=>!n||t.is_sampled(n),a=(a,r)=>{let o=new Set,s=new Set,i=r.sampler||n,d="boolean"!=typeof i,p=r.context||{};p["service.name"]=a,p["telemetry.sdk.name"]="rian",p["telemetry.sdk.version"]="0.3.0-next.1";let m="string"==typeof r.traceparent?t.parse(r.traceparent):void 0,c=(n,a)=>{let p=d?i(n,a,r.context):i,m=a?a.child(p):t.make(p),l={id:m,parent:a,start:Date.now(),name:n,events:[],context:{}};p&&o.add(l);let x=t=>e(x,t);return x.traceparent=m,x.span=e=>c(e,m),x.set_context=e=>"function"==typeof e?void(l.context=e(l.context)):void Object.assign(l.context,e),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=s.add.bind(s),x};return{span:e=>c(e,m),report:async()=>(s.size>0&&await Promise.all([...s.values()]),r.exporter(o,p))}};exports.create=a;
+const { measure:e } = require('rian/utils');const { make:t, parse:n, SAMPLED_FLAG:a } = require('tctx');const { is_sampled:r } = require('tctx');var o={};function s(e,t={}){o={...t,"service.name":e,"telemetry.sdk.name":"rian","telemetry.sdk.version":"0.3.0-next.11"}}var p=new Set,c=new WeakMap;async function i(e){let t=[],n=new Map;for(let[e,a]of p){let r;n.has(a)?r=n.get(a).spans:n.set(a,{scope:a,spans:r=[]}),r.push(e),c.has(a)&&(t.push(...c.get(a)),c.delete(a))}return p.clear(),t.length&&await Promise.all(t),e({resource:o,scopeSpans:n.values()})}function l(e,t){return r(t)}function d(a,r){let o=r?.sampler??l,s=r?.clock??Date,i={name:a},d=new Set;c.set(i,d);let m="string"==typeof r?.traceparent?n(r.traceparent):void 0,u=(n,a)=>{let r=a?a.child():t(),c="boolean"!=typeof o?o(n,r,i):o;r.flags;let l={id:r,parent:a,start:s.now(),name:n,events:[],context:{}};c&&p.add([l,i]);let m=t=>e(m,t);return m.traceparent=r,m.span=e=>u(e,r),m.set_context=e=>"function"==typeof e?void(l.context=e(l.context)):void Object.assign(l.context,e),m.add_event=(e,t)=>{l.events.push({name:e,timestamp:s.now(),attributes:t||{}})},m.end=()=>{null==l.end&&(l.end=s.now())},m.__add_promise=e=>{d.add(e),e.then((()=>d.delete(e)))},m};return{span:e=>u(e,m)}}exports.configure=s;exports.report=i;exports.tracer=d;

package/index.mjs

@@ -1 +1 @@
-import{measureFn as e}from"rian/utils";import*as t from"tctx";var n=(e,n)=>!n||t.is_sampled(n),a=(a,r)=>{let o=new Set,s=new Set,i=r.sampler||n,d="boolean"!=typeof i,p=r.context||{};p["service.name"]=a,p["telemetry.sdk.name"]="rian",p["telemetry.sdk.version"]="0.3.0-next.1";let m="string"==typeof r.traceparent?t.parse(r.traceparent):void 0,c=(n,a)=>{let p=d?i(n,a,r.context):i,m=a?a.child(p):t.make(p),l={id:m,parent:a,start:Date.now(),name:n,events:[],context:{}};p&&o.add(l);let x=t=>e(x,t);return x.traceparent=m,x.span=e=>c(e,m),x.set_context=e=>"function"==typeof e?void(l.context=e(l.context)):void Object.assign(l.context,e),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=s.add.bind(s),x};return{span:e=>c(e,m),report:async()=>(s.size>0&&await Promise.all([...s.values()]),r.exporter(o,p))}};export{a as create};
+import{measure as e}from"rian/utils";import{make as t,parse as n,SAMPLED_FLAG as a}from"tctx";import{is_sampled as r}from"tctx";var o={};function s(e,t={}){o={...t,"service.name":e,"telemetry.sdk.name":"rian","telemetry.sdk.version":"0.3.0-next.11"}}var p=new Set,c=new WeakMap;async function i(e){let t=[],n=new Map;for(let[e,a]of p){let r;n.has(a)?r=n.get(a).spans:n.set(a,{scope:a,spans:r=[]}),r.push(e),c.has(a)&&(t.push(...c.get(a)),c.delete(a))}return p.clear(),t.length&&await Promise.all(t),e({resource:o,scopeSpans:n.values()})}function l(e,t){return r(t)}function d(a,r){let o=r?.sampler??l,s=r?.clock??Date,i={name:a},d=new Set;c.set(i,d);let m="string"==typeof r?.traceparent?n(r.traceparent):void 0,u=(n,a)=>{let r=a?a.child():t(),c="boolean"!=typeof o?o(n,r,i):o;r.flags;let l={id:r,parent:a,start:s.now(),name:n,events:[],context:{}};c&&p.add([l,i]);let m=t=>e(m,t);return m.traceparent=r,m.span=e=>u(e,r),m.set_context=e=>"function"==typeof e?void(l.context=e(l.context)):void Object.assign(l.context,e),m.add_event=(e,t)=>{l.events.push({name:e,timestamp:s.now(),attributes:t||{}})},m.end=()=>{null==l.end&&(l.end=s.now())},m.__add_promise=e=>{d.add(e),e.then((()=>d.delete(e)))},m};return{span:e=>u(e,m)}}export{s as configure,i as report,d as tracer};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rian",
-	"version": "0.3.0-next.1",
+	"version": "0.3.0-next.11",
 	"description": "Effective tracing for the edge and origins",
 	"keywords": [
 		"opentelemetry",
@@ -25,20 +25,25 @@
 			"import": "./index.mjs",
 			"require": "./index.js"
 		},
+		"./async": {
+			"types": "./async.d.ts",
+			"import": "./async.mjs",
+			"require": "./async.js"
+		},
 		"./exporter.otel.http": {
-			"types": "./exporter.otel.http/index.d.ts",
-			"import": "./exporter.otel.http/index.mjs",
-			"require": "./exporter.otel.http/index.js"
+			"types": "./exporter.otel.http.d.ts",
+			"import": "./exporter.otel.http.mjs",
+			"require": "./exporter.otel.http.js"
 		},
 		"./exporter.zipkin": {
-			"types": "./exporter.zipkin/index.d.ts",
-			"import": "./exporter.zipkin/index.mjs",
-			"require": "./exporter.zipkin/index.js"
+			"types": "./exporter.zipkin.d.ts",
+			"import": "./exporter.zipkin.mjs",
+			"require": "./exporter.zipkin.js"
 		},
 		"./utils": {
-			"types": "./utils/index.d.ts",
-			"import": "./utils/index.mjs",
-			"require": "./utils/index.js"
+			"types": "./utils.d.ts",
+			"import": "./utils.mjs",
+			"require": "./utils.js"
 		},
 		"./package.json": "./package.json"
 	},
@@ -49,6 +54,7 @@
 		"*.mjs",
 		"*.js",
 		"*.d.ts",
+		"!global.d.ts",
 		"exporter.*/*",
 		"utils/*"
 	],

package/readme.md

@@ -6,9 +6,6 @@
 
 <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>
@@ -26,80 +23,136 @@
 
 ## ⚡ Features
 
-- 🤔 **Familiar** — looks very much like OpenTracing.
+- 🤔 **Familiar** — looks very much like opentelemetry.
 
-- ✅ **Simple** — `create` a tracer, and `.report()` a tracer, done.
+- ✅ **Simple** — `configure()` an environment, create a `tracer()`, `report()` and done.
 
 - 🏎 **Performant** — check the [benchmarks](#-benchmark).
 
-- 🪶 **Lightweight** — a mere 1Kb and next to no [dependencies](https://npm.anvaka.com/#/view/2d/rian/).
+- 🪶 **Lightweight** — a mere 1KB and next to no [dependencies](https://npm.anvaka.com/#/view/2d/rian/).
 
 ## 🚀 Usage
 
-> Visit [/examples](/examples) for more info!
+> Visit [/examples](/examples) for more!
 
 ```ts
-import { create } from 'rian';
-import { measure } from 'rian/utils';
+import { configure, tracer, report } from 'rian';
 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('my-service', {
-  exporter: otel_endpoint,
+// ~> configure the environment, all tracers will inherit this
+configure('my-service' {
+  'service.version': 'DEV'
 });
 
-// Let us trace
+// ~> create a tracer — typically "per request" or "per operation".
+const trace = tracer('request');
 
-const req = tracer.span('GET ~> /data');
+function handler(req) {
+  // ~> start a span
+  return trace.span(`${req.method} ${req.path}`)(async (s) => {
+    // set some fields on this span's context
+    s.set_context({ user_id: req.params.user_id });
 
-req.set_context({
-  user: request_context.user_id,
-});
+    // ~> span again for `db::read`
+    const data = await s.span('db::read')(() => db_execute('SELECT * FROM users'));
 
-// ~> Wrap any method and be timed 🕺🏻
-const data = await measure(req.span('db::read'), get_data);
+    // ~> maybe have some manual spanning
+    const processing_span = s.span('process records');
 
-// ~> Maybe have some in-flow spanning
-const span = req.span('process records');
+    for (let row of data) {
+      processing_span.add_event('doing stuff', { id: row.id });
+      do_stuff(row);
+    }
 
-for (let row of data) {
-  span.add_event('doing stuff', { id: row.id });
-  do_stuff(row);
-}
+    // don't forget to end
+    processing_span.end();
 
-span.end();
+    return reply(200, { data });
+  });
+}
 
-req.end();
+const otel_exporter = exporter((payload) =>
+  fetch('/traces/otlp', {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  }),
+);
 
-// ~> And finally let's export — will also end the root span.
-await tracer.report();
+http.listen((req, executionCtx) => {
+  // ~> report all the spans once the response is sent
+  executionCtx.defer(() => report(otel_exporter));
+  return handler(req);
+});
 
 /*
 And we end up with something like this in our reporting tool:
 
-[ GET ~> /data .................................... (1.2ms) ]
-   [ db::read .... (0.5ms) ]
-                           [ process records .... (0.5ms) ]
+[ GET /data .................,,...................... (1.2ms) ] { request }
+   [ db::read .... (0.5ms) ] [ process records .... (0.5ms) ]
+   ^                           ^             ^            ^
+   { user_id }                 ev { id: 1 }  |            |
+                                             ev { id: 2 } |
+                                                          ev { id: 3 }
  */
 ```
 
+You only need to `report` in your application once somewhere. All spans are collected into the same "bucket".
+
 ## 🔎 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.
+> 💡 Note ~> when providing span context values, you can use
+> [Semantic Conventions](https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/), but won't
+> be enforced.
+
+#### Module: [`rian/async`](./packages/rian/src/async.ts)
+
+A module that utilizes the `async_hooks` API to provide a `tracer` and `spans` that can be used where the current span
+isn't accessible.
+
+> 💡 Note ~> this module should be used mutually exclusively with the main `rian` module.
+
+<detials>
+
+<summary>Example</summary>
+
+```ts
+import { configure, tracer, span, currentSpan, report } from 'rian/async';
+import { exporter } from 'rian/exporter.otel.http';
+
+function handler(req) {
+  return span(`${req.method} ${req.path}`)(async () => {
+    const s = currentSpan();
+
+    s.set_context({ user_id: req.params.user_id });
+
+    const data = await s.span('db::read')(() => db_execute('SELECT * FROM users'));
+
+    const processing_span = s.span('process records');
+
+    for (let row of data) {
+      processing_span.add_event('doing stuff', { id: row.id });
+      do_stuff(row);
+    }
+
+    processing_span.end();
+
+    return reply(200, { data });
+  });
+}
+
+const httpTrace = tracer('http');
+
+http.listen((req, executionCtx) => {
+  executionCtx.defer(() => report(exporter));
+  return httpTrace(() => handler(req));
+});
+```
+
+</details>
 
 #### Module: [`rian/exporter.zipkin`](./packages/rian/src/exporter.zipkin.ts)
 
@@ -114,7 +167,7 @@ Implements the OpenTelemetry protocol for use with http transports.
 <details><summary>NewRelic</summary>
 
 ```ts
-import { create } from 'rian';
+import { configure, tracer, report } from 'rian';
 import { exporter } from 'rian/exporter.zipkin';
 
 const newrelic = exporter((payload) =>
@@ -130,23 +183,25 @@ const newrelic = exporter((payload) =>
   }),
 );
 
-const tracer = create('my-service', {
-  exporter: newrelic,
-});
+configure('my-service');
+
+const tracer = tracer('app');
+
+await report(newrelic);
 ```
 
 [learn more](https://docs.newrelic.com/docs/distributed-tracing/trace-api/introduction-trace-api/)
 
 </details>
 
-<details><summary>LightStep</summary>
+<details><summary>Lightstep</summary>
 
 ```ts
-import { create } from 'rian';
+import { configure, tracer, report } from 'rian';
 import { exporter } from 'rian/exporter.otel.http';
 
 const lightstep = exporter((payload) =>
-  fetch('https://ingest.lightstep.com/traces/otlp/v0.6', {
+  fetch('https://ingest.lightstep.com/traces/otlp/v0.9', {
     method: 'POST',
     headers: {
       'lightstep-access-token': '<your api key>',
@@ -156,9 +211,11 @@ const lightstep = exporter((payload) =>
   }),
 );
 
-const tracer = create('my-service', {
-  exporter: lightstep,
-});
+configure('my-service');
+
+const tracer = tracer('app');
+
+await report(lightstep);
 ```
 
 [learn more](https://opentelemetry.lightstep.com/tracing/)
@@ -167,34 +224,23 @@ const tracer = create('my-service', {
 
 ## 🤔 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.
+To clarify, `rian` is the Irish word for "trace".
 
-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".
+In our efforts to be observant citizens, we often rely on tools such as NewRelic, Lightstep, and Datadog. However, these
+tools can be bloated and slow, often performing too many unnecessary tasks and driving up costs, as every span costs.
 
-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.
+This is where rian comes in as a lightweight, fast, and effective tracer inspired by industry giants OpenTracing and
+OpenTelemetry. These frameworks were designed to abstract the telemetry part from vendors, allowing libraries to be
+instrumented without needing to know about the vendor.
 
-You see, the primary design goal is targeted at edge or service workers — where lean quick tracers is favoured.
+Rian does not intend to align or compete with them, slightly different goals. Rian aims to be used exclusively for
+instrumenting your application, particularly critical business paths. While rian can scale to support more complex
+constructs, there are profiler tools that are better suited for those jobs. Rian's primary design goal is to provide
+better insights into your application's behavior, particularly for edge or service workers where a lean tracer is
+favored.
 
-Rian is still in active development, but ready for production!
+Rian does not by design handle injecting [`w3c trace-context`](https://www.w3.org/TR/trace-context/), or
+[propagating baggage](https://www.w3.org/TR/baggage/). But we do expose api's for achieving this.
 
 ## 💨 Benchmark
 
@@ -204,22 +250,18 @@ Rian is still in active development, but ready for production!
 Validation :: single span
 ✔ rian
 ✔ opentelemetry
-✔ opentracing
 
 Benchmark :: single span
-  rian                   x 392,796 ops/sec ±3.73% (86 runs sampled)
-  opentelemetry          x 205,544 ops/sec ±11.98% (65 runs sampled)
-  opentracing            x  60,043 ops/sec ±35.25% (97 runs sampled)
+  rian                   x 339,110 ops/sec ±2.11% (89 runs sampled)
+  opentelemetry          x 199,246 ops/sec ±14.78% (67 runs sampled)
 
 Validation :: child span
 ✔ rian
 ✔ opentelemetry
-✔ opentracing
 
 Benchmark :: child span
-  rian                   x 208,186 ops/sec ±6.28% (82 runs sampled)
-  opentelemetry          x 121,740 ops/sec ±16.56% (62 runs sampled)
-  opentracing            x  37,405 ops/sec ±0.48% (99 runs sampled)
+  rian                   x 176,936 ops/sec ±2.30% (88 runs sampled)
+  opentelemetry          x 124,447 ops/sec ±13.72% (70 runs sampled)
 ```
 
 > And please... I know these results are anything but the full story. But it's a number and point on comparison.
@@ -231,5 +273,5 @@ 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>
+<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.d.ts

@@ -0,0 +1,25 @@
+import type { Scope } from 'rian';
+
+/**
+ * With a passed function, `measure` will run the function and once finishes, will end the span.
+ *
+ * The measure method will return whatever the function is, so if it's a promise, it returns a
+ * promise and so on. Any error is caught and re thrown, and automatically tracked in the
+ * context under the `error` property.
+ *
+ * All promises are tracked, and awaited on a `report`.
+ *
+ * This is a utility method, but is functionally equivalent to `scope.span('name')(fn)`.
+ *
+ * @example
+ *
+ * ```text
+ * const data = await measure(scope, get_data);
+ * // or with arguments:
+ * const data = await measure(scope, () => get_data('foo', 'bar'));
+ * ```
+ */
+export function measure<Fn extends (scope: Scope) => any>(
+	scope: Scope,
+	fn: Fn,
+): ReturnType<Fn>;

package/utils.js

@@ -0,0 +1 @@
+function r(r,t){try{var e=t(r),n=e instanceof Promise;return n&&r.__add_promise(e.catch((t=>{r.set_context({error:t})})).finally((()=>r.end()))),e}catch(t){throw t instanceof Error&&r.set_context({error:t}),t}finally{!0!==n&&r.end()}}exports.measure=r;

package/utils.mjs

@@ -0,0 +1 @@
+function r(r,t){try{var e=t(r),n=e instanceof Promise;return n&&r.__add_promise(e.catch((t=>{r.set_context({error:t})})).finally((()=>r.end()))),e}catch(t){throw t instanceof Error&&r.set_context({error:t}),t}finally{!0!==n&&r.end()}}export{r as measure};

package/exporter.otel.http/index.js

@@ -1 +0,0 @@
-var e=r=>{let n=typeof r,a={};return"string"===n?a.stringValue=r:"number"===n?Number.isInteger(r)?a.intValue=r:a.doubleValue=r:"boolean"===n?a.boolValue=r:Array.isArray(r)?a.arrayValue={values:r.map((t=>e(t)))}:r&&(a.kvlistValue={values:t(r)}),a},t=t=>{let r=[];for(let n of Object.keys(t))r.push({key:n,value:e(t[n])});return r},r=e=>{switch(e){default:case"INTERNAL":return 1;case"SERVER":return 2;case"CLIENT":return 3;case"PRODUCER":return 4;case"CONSUMER":return 5}},n=e=>(n,a)=>{let s=[];for(let e of n){let n,{kind:a,error:u,...i}=e.context;u&&(n={code:2},"message"in u&&(n.message=u.message)),s.push({traceId:e.id.trace_id,spanId:e.id.parent_id,parentSpanId:e.parent?.parent_id,name:e.name,kind:r(a||"INTERNAL"),startTimeUnixNano:1e6*e.start,endTimeUnixNano:e.end?1e6*e.end:void 0,droppedAttributesCount:0,droppedEventsCount:0,droppedLinksCount:0,attributes:t(i),status:n||{code:0},events:e.events.map((e=>({name:e.name,attributes:t(e.attributes),droppedAttributesCount:0,timeUnixNano:1e6*e.timestamp})))})}return e({resourceSpans:[{resource:{attributes:t(a),droppedAttributesCount:0},instrumentationLibrarySpans:[{instrumentationLibrary:{name:"rian",version:"0.3.0-next.1"},spans:s}]}]})};exports.exporter=n;

package/exporter.otel.http/index.mjs

@@ -1 +0,0 @@
-var e=r=>{let n=typeof r,a={};return"string"===n?a.stringValue=r:"number"===n?Number.isInteger(r)?a.intValue=r:a.doubleValue=r:"boolean"===n?a.boolValue=r:Array.isArray(r)?a.arrayValue={values:r.map((t=>e(t)))}:r&&(a.kvlistValue={values:t(r)}),a},t=t=>{let r=[];for(let n of Object.keys(t))r.push({key:n,value:e(t[n])});return r},r=e=>{switch(e){default:case"INTERNAL":return 1;case"SERVER":return 2;case"CLIENT":return 3;case"PRODUCER":return 4;case"CONSUMER":return 5}},n=e=>(n,a)=>{let s=[];for(let e of n){let n,{kind:a,error:u,...i}=e.context;u&&(n={code:2},"message"in u&&(n.message=u.message)),s.push({traceId:e.id.trace_id,spanId:e.id.parent_id,parentSpanId:e.parent?.parent_id,name:e.name,kind:r(a||"INTERNAL"),startTimeUnixNano:1e6*e.start,endTimeUnixNano:e.end?1e6*e.end:void 0,droppedAttributesCount:0,droppedEventsCount:0,droppedLinksCount:0,attributes:t(i),status:n||{code:0},events:e.events.map((e=>({name:e.name,attributes:t(e.attributes),droppedAttributesCount:0,timeUnixNano:1e6*e.timestamp})))})}return e({resourceSpans:[{resource:{attributes:t(a),droppedAttributesCount:0},instrumentationLibrarySpans:[{instrumentationLibrary:{name:"rian",version:"0.3.0-next.1"},spans:s}]}]})};export{n as exporter};

package/exporter.zipkin/index.js

@@ -1 +0,0 @@
-const { flattie:e } = require('flattie');var t=t=>(a,r)=>{let n=[];for(let t of a){let{kind:a,error:i,...s}=t.context;i&&(s.error=!("message"in i)||{name:i.name,message:i.message,stack:i.stack}),n.push({id:t.id.parent_id,traceId:t.id.trace_id,parentId:t.parent?t.parent.parent_id:void 0,name:t.name,kind:"INTERNAL"===a?void 0:a,timestamp:1e3*t.start,duration:t.end?1e3*(t.end-t.start):void 0,localEndpoint:{serviceName:r["service.name"]},tags:e({...r,...s},".",!0),annotations:t.events.map((e=>({value:`${e.name} :: ${JSON.stringify(e.attributes)}`,timestamp:1e3*e.timestamp})))})}return t(n)};exports.exporter=t;

package/exporter.zipkin/index.mjs

@@ -1 +0,0 @@
-import{flattie as e}from"flattie";var t=t=>(a,r)=>{let n=[];for(let t of a){let{kind:a,error:i,...s}=t.context;i&&(s.error=!("message"in i)||{name:i.name,message:i.message,stack:i.stack}),n.push({id:t.id.parent_id,traceId:t.id.trace_id,parentId:t.parent?t.parent.parent_id:void 0,name:t.name,kind:"INTERNAL"===a?void 0:a,timestamp:1e3*t.start,duration:t.end?1e3*(t.end-t.start):void 0,localEndpoint:{serviceName:r["service.name"]},tags:e({...r,...s},".",!0),annotations:t.events.map((e=>({value:`${e.name} :: ${JSON.stringify(e.attributes)}`,timestamp:1e3*e.timestamp})))})}return t(n)};export{t as exporter};

package/utils/index.d.ts

@@ -1,66 +0,0 @@
-import type { Scope } from 'rian';
-
-export type MeasureFn =
-	| ((...args: [...args: any[]]) => any)
-	| ((...args: [...args: any[], scope: Scope]) => any);
-
-/**
- * With a passed function — will start a span, and run the function, when the function finishes
- * the span finishes.
- *
- * The measure method will return whatever the function is, so if it's a promise, it returns a
- * promise and so on. Any error is caught and re thrown, and automatically tracked in the
- * context under the `error` property.
- *
- * All promises are tracked, and awaited on a `tracer.end`.
- *
- * @example
- *
- * ```text
- * const data = await measure(scope, get_data, 'user_id_123');
- *       ^                    ^     ^          ^
- *       |                    |     |          |
- *       |                    |     |          the first argument to get_data
- *       |                    |     |
- *       |                    |     function to be called
- *       |                    |
- *       |                    the parent scope
- *       return value from get_data
- * ```
- */
-export const measure: <Fn extends MeasureFn>(
-	scope: Scope,
-	fn: Fn, // TODO: fn doesnt see scope correctly
-	...args: RealMeasureFnParams<Parameters<Fn>>
-) => ReturnType<Fn>;
-
-/**
- * Wraps any function with a measured scoped function. Useful for when defer function execution
- * till a later time.
- *
- * @example
- *
- * ```js
- * const wrapped = wrap(scope, "run something", my_function);
- *
- * // ... lots of things, where the access to `scope` is lost.
- *
- * wrapped();
- * ```
- */
-export const wrap: <Fn extends MeasureFn>(
-	scope: Scope,
-	fn: Fn, // TODO: fn doesnt see scope correctly
-) => Fn;
-
-// ==> internals
-
-/** @internal */
-export type RealMeasureFnParams<T extends unknown[]> = T extends []
-	? []
-	: T extends [...rest: infer U, scope: Scope]
-	? U
-	: T;
-
-/** @internal */
-export const measureFn: (scope: Scope, fn: any, ...args: any[]) => any;

package/utils/index.js

@@ -1 +0,0 @@
-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)=>r(t,e,...n),e=(t,e)=>function(){return r(t,e,...arguments)};exports.measure=t;exports.measureFn=r;exports.wrap=e;

package/utils/index.mjs

@@ -1 +0,0 @@
-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)=>r(t,e,...n),e=(t,e)=>function(){return r(t,e,...arguments)};export{t as measure,r as measureFn,e as wrap};