rian 0.3.0-next.9 → 0.3.1

package/index.d.ts

@@ -3,8 +3,7 @@ import type { Traceparent } from 'tctx';
 // --- tracer
 
 /**
- * An exporter is a method called when the parent scope ends, gets given a Set of all spans traced
- * during this execution.
+ * The exporter is called when the {@link report} method is called.
  */
 export type Exporter = (trace: {
 	resource: Context;
@@ -23,12 +22,14 @@ export type Options = {
 	sampler?: Sampler | boolean;
 
 	/**
-	 * A root, or extracted w3c traceparent stringed header.
+	 * 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.
+	 * 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'>;
@@ -41,17 +42,24 @@ export type Context = {
 };
 
 /**
- * Should return true when you want to sample the span, this is ran before the span is traced — so
- * decisions is made preemptively.
- *
- * Returning false will not include this span in the {@link Exporter}.
+ * Allows a sampling decision to be made. This method will influence the {@link Span.id|traceparent} sampling flag.
  *
- * Sampling does impact the traceparent, for injection — and is encoded there.
+ * 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,
-	readonly scope: { readonly name: string },
+	/**
+	 * The tracer this span belongs to.
+	 */
+	readonly tracer: { readonly name: string },
 ) => boolean;
 
 // --- spans
@@ -61,20 +69,15 @@ export type Sampler = (
  * {@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 type Span = {
 	/**
@@ -82,6 +85,7 @@ export type Span = {
 	 * or stage of the larger stack.
 	 *
 	 * @example
+	 *
 	 * "resolve_user_ids"
 	 * "[POST] /api"
 	 */
@@ -105,7 +109,7 @@ export type 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;
 
@@ -119,7 +123,7 @@ export type 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!
 	 *
@@ -153,7 +157,12 @@ export type 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
@@ -177,13 +186,33 @@ export type Scope = {
 };
 
 export type CallableScope = Scope & {
-	(cb: (scope: Omit<Scope, 'end'>) => void): ReturnType<typeof cb>;
+	<Fn extends (scope: Omit<Scope, 'end'>) => any>(cb: Fn): ReturnType<Fn>;
 };
 
 // --- main api
 
+/**
+ * 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 function tracer(name: string, options?: Options): Tracer;
 
+// -- general api
+
 /**
  * Awaits all active promises, and then calls the {@link Options.exporter|exporter}. Passing all collected spans.
  */
@@ -191,5 +220,30 @@ export async function report<T extends Exporter>(
 	exporter: T,
 ): Promise<ReturnType<T>>;
 
-// TODO
+/**
+ * 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 `name` argument will set the `service.name` attribute. And is required.
+ *
+ * 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 function configure(name: string, attributes: Context = {}): void;
+
+/**
+ * Provinding a clock allows you to control the time of the span.
+ */
+export type ClockLike = {
+	/**
+	 * Must return the number of milliseconds since the epoch.
+	 */
+	now(): number;
+};

package/index.js

@@ -1,74 +1 @@
-// src/index.ts
-const { measureFn } = require('rian/utils');
-const { make, parse, SAMPLED_FLAG } = require('tctx');
-
-// src/_internal/index.ts
-const { is_sampled } = require('tctx');
-var resource = {};
-function configure(name, attributes = {}) {
-  resource = {
-    ...attributes,
-    ["service.name"]: name,
-    ["telemetry.sdk.name"]: "rian",
-    ["telemetry.sdk.version"]: "0.3.0-next.9"
-  };
-}
-var span_buffer = /* @__PURE__ */ new Set(), wait_promises = /* @__PURE__ */ new WeakMap();
-async function report(exporter) {
-  let ps = [], scopes = /* @__PURE__ */ new Map();
-  for (let [span, scope] of span_buffer) {
-    let spans;
-    scopes.has(scope) ? spans = scopes.get(scope).spans : scopes.set(scope, {
-      scope,
-      spans: spans = []
-    }), spans.push(span), wait_promises.has(scope) && (ps.push(...wait_promises.get(scope)), wait_promises.delete(scope));
-  }
-  return span_buffer.clear(), ps.length && await Promise.all(ps), exporter({
-    resource,
-    scopeSpans: scopes.values()
-  });
-}
-function defaultSampler(_name, id) {
-  return is_sampled(id);
-}
-
-// src/index.ts
-function tracer(name, options) {
-  let sampler = options?.sampler ?? defaultSampler, scope = { name }, ps = /* @__PURE__ */ new Set();
-  wait_promises.set(scope, ps);
-  let root_id = typeof options?.traceparent == "string" ? parse(options.traceparent) : void 0, span = (name2, parent) => {
-    let id = parent ? parent.child() : make(), should_sample = typeof sampler != "boolean" ? sampler(name2, id, scope) : sampler;
-    should_sample ? id.flags | SAMPLED_FLAG : id.flags & ~SAMPLED_FLAG;
-    let span_obj = {
-      id,
-      parent,
-      start: Date.now(),
-      name: name2,
-      events: [],
-      context: {}
-    };
-    should_sample && span_buffer.add([span_obj, scope]);
-    let $ = (cb) => measureFn($, cb);
-    return $.traceparent = id, $.span = (name3) => span(name3, id), $.set_context = (ctx) => typeof ctx == "function" ? void (span_obj.context = ctx(span_obj.context)) : void Object.assign(span_obj.context, ctx), $.add_event = (name3, attributes) => {
-      span_obj.events.push({
-        name: name3,
-        timestamp: Date.now(),
-        attributes: attributes || {}
-      });
-    }, $.end = () => {
-      span_obj.end == null && (span_obj.end = Date.now());
-    }, $.__add_promise = (p) => {
-      ps.add(p), p.then(() => ps.delete(p));
-    }, $;
-  };
-  return {
-    span(name2) {
-      return span(name2, root_id);
-    }
-  };
-}
-
-
-exports.configure = configure;
-exports.report = report;
-exports.tracer = tracer;
+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.1"}}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,74 +1 @@
-// src/index.ts
-import { measureFn } from "rian/utils";
-import { make, parse, SAMPLED_FLAG } from "tctx";
-
-// src/_internal/index.ts
-import { is_sampled } from "tctx";
-var resource = {};
-function configure(name, attributes = {}) {
-  resource = {
-    ...attributes,
-    ["service.name"]: name,
-    ["telemetry.sdk.name"]: "rian",
-    ["telemetry.sdk.version"]: "0.3.0-next.9"
-  };
-}
-var span_buffer = /* @__PURE__ */ new Set(), wait_promises = /* @__PURE__ */ new WeakMap();
-async function report(exporter) {
-  let ps = [], scopes = /* @__PURE__ */ new Map();
-  for (let [span, scope] of span_buffer) {
-    let spans;
-    scopes.has(scope) ? spans = scopes.get(scope).spans : scopes.set(scope, {
-      scope,
-      spans: spans = []
-    }), spans.push(span), wait_promises.has(scope) && (ps.push(...wait_promises.get(scope)), wait_promises.delete(scope));
-  }
-  return span_buffer.clear(), ps.length && await Promise.all(ps), exporter({
-    resource,
-    scopeSpans: scopes.values()
-  });
-}
-function defaultSampler(_name, id) {
-  return is_sampled(id);
-}
-
-// src/index.ts
-function tracer(name, options) {
-  let sampler = options?.sampler ?? defaultSampler, scope = { name }, ps = /* @__PURE__ */ new Set();
-  wait_promises.set(scope, ps);
-  let root_id = typeof options?.traceparent == "string" ? parse(options.traceparent) : void 0, span = (name2, parent) => {
-    let id = parent ? parent.child() : make(), should_sample = typeof sampler != "boolean" ? sampler(name2, id, scope) : sampler;
-    should_sample ? id.flags | SAMPLED_FLAG : id.flags & ~SAMPLED_FLAG;
-    let span_obj = {
-      id,
-      parent,
-      start: Date.now(),
-      name: name2,
-      events: [],
-      context: {}
-    };
-    should_sample && span_buffer.add([span_obj, scope]);
-    let $ = (cb) => measureFn($, cb);
-    return $.traceparent = id, $.span = (name3) => span(name3, id), $.set_context = (ctx) => typeof ctx == "function" ? void (span_obj.context = ctx(span_obj.context)) : void Object.assign(span_obj.context, ctx), $.add_event = (name3, attributes) => {
-      span_obj.events.push({
-        name: name3,
-        timestamp: Date.now(),
-        attributes: attributes || {}
-      });
-    }, $.end = () => {
-      span_obj.end == null && (span_obj.end = Date.now());
-    }, $.__add_promise = (p) => {
-      ps.add(p), p.then(() => ps.delete(p));
-    }, $;
-  };
-  return {
-    span(name2) {
-      return span(name2, root_id);
-    }
-  };
-}
-export {
-  configure,
-  report,
-  tracer
-};
+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.1"}}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.9",
+	"version": "0.3.1",
 	"description": "Effective tracing for the edge and origins",
 	"keywords": [
 		"opentelemetry",
@@ -60,7 +60,7 @@
 	],
 	"scripts": {
 		"bench": "node -r tsm bench/index.ts",
-		"build": "bundt",
+		"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$\"",