rian 0.0.2-alpha.10 → 0.0.2-alpha.11

package/exporter.otel.http.d.ts

@@ -0,0 +1,8 @@
+import * as rian from 'rian';
+
+interface Config {
+    onRequest(payload: any): void;
+}
+declare const exporter: (config: Config) => rian.Exporter;
+
+export { Config, exporter };

package/exporter.otel.http.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const package_json = require('rian/package.json');
+
+const SpanStatusCode_UNSET = 0;
+const SpanStatusCode_ERROR = 2;
+const convert_value_to_anyvalue = (value) => {
+    let type = typeof value, any_value = {};
+    if (type === 'string')
+        any_value.stringValue = value;
+    else if (type === 'number')
+        if (Number.isInteger(value))
+            any_value.intValue = value;
+        else
+            any_value.doubleValue = value;
+    else if (type === 'boolean')
+        any_value.boolValue = value;
+    else if (Array.isArray(value))
+        any_value.arrayValue = {
+            values: value.map((i) => convert_value_to_anyvalue(i)),
+        };
+    else
+        any_value.kvlistValue = { values: convert_object_to_kv(value) };
+    return any_value;
+};
+const convert_object_to_kv = (input) => {
+    const value = [];
+    for (let key of Object.keys(input)) {
+        value.push({
+            key,
+            value: convert_value_to_anyvalue(input[key]),
+        });
+    }
+    return value;
+};
+// https://github.com/open-telemetry/opentelemetry-proto/blob/b43e9b18b76abf3ee040164b55b9c355217151f3/opentelemetry/proto/trace/v1/trace.proto#L127-L155
+const map_kind = (kind) => {
+    switch (kind) {
+        default:
+        case 'INTERNAL': {
+            return 1;
+        }
+        case 'SERVER': {
+            return 2;
+        }
+        case 'CLIENT': {
+            return 3;
+        }
+        case 'PRODUCER': {
+            return 4;
+        }
+        case 'CONSUMER': {
+            return 5;
+        }
+    }
+};
+const exporter = (config) => (spans, context) => {
+    const otel_spans = [];
+    for (let span of spans) {
+        const kind = span.context.kind;
+        delete span.context.kind;
+        let status;
+        if ('error' in span.context) {
+            status = {
+                code: SpanStatusCode_ERROR,
+            };
+            if ('message' in span.context.error) {
+                status.message = span.context.error.message;
+            }
+            delete span.context.error;
+        }
+        otel_spans.push({
+            traceId: span.id.trace_id,
+            spanId: span.id.parent_id,
+            parentSpanId: span.parent?.parent_id,
+            name: span.name,
+            kind: map_kind(kind || 'INTERNAL'),
+            startTimeUnixNano: span.start * 1000000,
+            endTimeUnixNano: span.end ? span.end * 1000000 : undefined,
+            droppedAttributesCount: 0,
+            droppedEventsCount: 0,
+            droppedLinksCount: 0,
+            attributes: convert_object_to_kv(span.context),
+            status: status || { code: SpanStatusCode_UNSET },
+        });
+    }
+    return config.onRequest({
+        resourceSpans: [
+            {
+                resource: {
+                    attributes: convert_object_to_kv(context),
+                    droppedAttributesCount: 0,
+                },
+                instrumentationLibrarySpans: [
+                    {
+                        instrumentationLibrary: {
+                            name: package_json.name,
+                            version: package_json.version,
+                        },
+                        spans: otel_spans,
+                    },
+                ],
+            },
+        ],
+    });
+};
+
+exports.exporter = exporter;

package/exporter.otel.http.mjs

@@ -0,0 +1,106 @@
+import { name, version } from 'rian/package.json';
+
+const SpanStatusCode_UNSET = 0;
+const SpanStatusCode_ERROR = 2;
+const convert_value_to_anyvalue = (value) => {
+    let type = typeof value, any_value = {};
+    if (type === 'string')
+        any_value.stringValue = value;
+    else if (type === 'number')
+        if (Number.isInteger(value))
+            any_value.intValue = value;
+        else
+            any_value.doubleValue = value;
+    else if (type === 'boolean')
+        any_value.boolValue = value;
+    else if (Array.isArray(value))
+        any_value.arrayValue = {
+            values: value.map((i) => convert_value_to_anyvalue(i)),
+        };
+    else
+        any_value.kvlistValue = { values: convert_object_to_kv(value) };
+    return any_value;
+};
+const convert_object_to_kv = (input) => {
+    const value = [];
+    for (let key of Object.keys(input)) {
+        value.push({
+            key,
+            value: convert_value_to_anyvalue(input[key]),
+        });
+    }
+    return value;
+};
+// https://github.com/open-telemetry/opentelemetry-proto/blob/b43e9b18b76abf3ee040164b55b9c355217151f3/opentelemetry/proto/trace/v1/trace.proto#L127-L155
+const map_kind = (kind) => {
+    switch (kind) {
+        default:
+        case 'INTERNAL': {
+            return 1;
+        }
+        case 'SERVER': {
+            return 2;
+        }
+        case 'CLIENT': {
+            return 3;
+        }
+        case 'PRODUCER': {
+            return 4;
+        }
+        case 'CONSUMER': {
+            return 5;
+        }
+    }
+};
+const exporter = (config) => (spans, context) => {
+    const otel_spans = [];
+    for (let span of spans) {
+        const kind = span.context.kind;
+        delete span.context.kind;
+        let status;
+        if ('error' in span.context) {
+            status = {
+                code: SpanStatusCode_ERROR,
+            };
+            if ('message' in span.context.error) {
+                status.message = span.context.error.message;
+            }
+            delete span.context.error;
+        }
+        otel_spans.push({
+            traceId: span.id.trace_id,
+            spanId: span.id.parent_id,
+            parentSpanId: span.parent?.parent_id,
+            name: span.name,
+            kind: map_kind(kind || 'INTERNAL'),
+            startTimeUnixNano: span.start * 1000000,
+            endTimeUnixNano: span.end ? span.end * 1000000 : undefined,
+            droppedAttributesCount: 0,
+            droppedEventsCount: 0,
+            droppedLinksCount: 0,
+            attributes: convert_object_to_kv(span.context),
+            status: status || { code: SpanStatusCode_UNSET },
+        });
+    }
+    return config.onRequest({
+        resourceSpans: [
+            {
+                resource: {
+                    attributes: convert_object_to_kv(context),
+                    droppedAttributesCount: 0,
+                },
+                instrumentationLibrarySpans: [
+                    {
+                        instrumentationLibrary: {
+                            name: name,
+                            version: version,
+                        },
+                        spans: otel_spans,
+                    },
+                ],
+            },
+        ],
+    });
+};
+
+export { exporter };

package/exporter.zipkin.d.ts

@@ -0,0 +1,8 @@
+import * as rian from 'rian';
+
+interface Config {
+    onRequest(payload: any): void;
+}
+declare const exporter: (config: Config) => rian.Exporter;
+
+export { Config, exporter };

package/exporter.zipkin.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const flattie = require('flattie');
+
+const exporter = (config) => (spans, context) => {
+    const zipkin = [];
+    for (let span of spans) {
+        const kind = span.context.kind;
+        delete span.context.kind;
+        if ('error' in span.context) {
+            const error = span.context.error;
+            if ('message' in error) {
+                span.context.error = {
+                    name: error.name,
+                    message: error.message,
+                    stack: error.stack,
+                };
+            }
+            else {
+                span.context.error = true;
+            }
+        }
+        zipkin.push({
+            id: span.id.parent_id,
+            traceId: span.id.trace_id,
+            parentId: span.parent?.parent_id,
+            name: span.name,
+            kind: kind === 'INTERNAL' ? undefined : kind,
+            timestamp: span.start * 1000,
+            duration: span.end ? (span.end - span.start) * 1000 : undefined,
+            localEndpoint: context.localEndpoint,
+            tags: flattie.flattie(Object.assign({}, context, span.context), '.', true),
+        });
+    }
+    return config.onRequest(zipkin);
+};
+
+exports.exporter = exporter;

package/exporter.zipkin.mjs

@@ -0,0 +1,36 @@
+import { flattie } from 'flattie';
+
+const exporter = (config) => (spans, context) => {
+    const zipkin = [];
+    for (let span of spans) {
+        const kind = span.context.kind;
+        delete span.context.kind;
+        if ('error' in span.context) {
+            const error = span.context.error;
+            if ('message' in error) {
+                span.context.error = {
+                    name: error.name,
+                    message: error.message,
+                    stack: error.stack,
+                };
+            }
+            else {
+                span.context.error = true;
+            }
+        }
+        zipkin.push({
+            id: span.id.parent_id,
+            traceId: span.id.trace_id,
+            parentId: span.parent?.parent_id,
+            name: span.name,
+            kind: kind === 'INTERNAL' ? undefined : kind,
+            timestamp: span.start * 1000,
+            duration: span.end ? (span.end - span.start) * 1000 : undefined,
+            localEndpoint: context.localEndpoint,
+            tags: flattie(Object.assign({}, context, span.context), '.', true),
+        });
+    }
+    return config.onRequest(zipkin);
+};
+
+export { exporter };

package/index.d.ts

@@ -1,37 +1,142 @@
 import { Traceparent } from 'tctx';
+import { Scope as Scope$1 } from 'rian';
 
-declare type Span = {
+declare type MeasureFn = ((...args: [...args: any[]]) => any) | ((...args: [...args: any[], scope: Scope$1]) => any);
+declare type RealMeasureFnParams<T extends unknown[]> = T extends [] ? [] : T extends [...rest: infer U, scope: Scope$1] ? U : T;
+
+/**
+ * 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".
+ *
+ * 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)]
+ * ```
+ *
+ * ---
+ *
+ * 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.
+ */
+interface 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"
+     */
     name: string;
+    /**
+     * A w3c trace context compatible id for this span. Will .toString() into an injectable header.
+     *
+     * @see https://www.w3.org/TR/trace-context/#traceparent-header
+     * @see https://github.com/maraisr/tctx
+     */
     id: Traceparent;
+    /**
+     * Is the id of rhe parent if this is not the parent {@link Span}.
+     *
+     * @see {@link Span.id}
+     */
     parent?: Traceparent;
+    /**
+     * The time represented as a UNIX epoch timestamp in milliseconds when this span was created.
+     * Typically, via
+     * {@link Scope.fork|tracer.fork()}.
+     */
     start: number;
-    end: number;
+    /**
+     * The UNIX epoch timestamp in milliseconds when the span ended, or undefined if ending was not
+     * captured during the current trace. Time should then be assumed as current time.
+     */
+    end?: number;
+    /**
+     * 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}.
+     *
+     * ### Note!
+     *
+     * There are a few keys with "powers"
+     *
+     * - `kind` when set will coerce into the exports scheme, aka INTERNAL in zipkin will be
+     * `"INTERNAL"`, or `1` in otel
+     * - `error` when set, will be assumed to be an `Error` instance, and thus its `.message` wil
+     * exist as `error.message` in zipkin, and `status: 2` in otel.
+     */
     context: Context;
-};
-declare type Collector = (spans: ReadonlySet<Span>) => any;
-declare type Context = {
+}
+/**
+ * An exporter is a method called when the parent scope ends, gets given a Set of all spans traced
+ * during this execution.
+ */
+declare type Exporter = (spans: ReadonlySet<Span>, context: Context) => any;
+/**
+ * @borrows {@link Span.context}
+ */
+interface Context {
     [property: string]: any;
-};
-declare type Options = {
-    collector: Collector;
+}
+/**
+ * Should return true when you want to sample the span, this is ran before the span is traced — so
+ * decisions is made preemptively.
+ *
+ * The Span itself will still be included in the {@link Options.exporter|exporter}, and can be
+ * filtered out there.
+ *
+ * Sampling does impact the traceparent, for injection — and is encoded there.
+ */
+declare type Sampler = (name: string, parentId?: Traceparent, context?: Context) => boolean;
+interface Options {
+    /**
+     * @borrows {@link Exporter}
+     */
+    exporter: Exporter;
+    /**
+     * @borrows {@link Sampler}
+     */
+    sampler?: Sampler;
+    context?: Context;
+    /**
+     * 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.
+     */
     traceparent?: string;
-};
-declare type OmitScopeParam<T extends unknown[]> = T extends [] ? [] : T extends [infer H, ...infer R] ? H extends Scope ? OmitScopeParam<R> : [H, ...OmitScopeParam<R>] : T;
+}
 interface CallableScope extends Scope {
     (cb: (scope: Omit<Scope, 'end'>) => void): ReturnType<typeof cb>;
 }
 interface Scope {
     traceparent: Traceparent;
-    fork(name: string, traceparent?: Traceparent): CallableScope;
-    measure<Fn extends (...args: any[]) => any, Params extends Parameters<Fn>>(name: string, fn: Fn, // TODO Fix types here
-    ...args: OmitScopeParam<Params>): ReturnType<Fn>;
+    fork(name: string): CallableScope;
+    measure<Fn extends MeasureFn>(name: string, fn: Fn, // TODO: fn doesnt see scope correctly
+    ...args: RealMeasureFnParams<Parameters<Fn>>): ReturnType<Fn>;
     set_context(contextFn: (context: Context) => Context): void;
     set_context(context: Context): void;
     end(): void;
 }
-interface Tracer extends Scope {
-    end(): ReturnType<Collector>;
+interface Tracer {
+    /**
+     * @borrows {@link Scope.fork}
+     */
+    span: Scope['fork'];
+    /**
+     * @borrows {@link Scope.measure}
+     */
+    measure: Scope['measure'];
+    end(): ReturnType<Exporter>;
 }
 declare const create: (name: string, options: Options) => Tracer;
 
-export { Collector, Context, Options, Scope, Span, Tracer, create };
+export { Context, Exporter, Options, Sampler, Scope, Span, Tracer, create };

package/index.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const package_json = require('rian/package.json');
 const tctx = require('tctx');
 
 function _interopNamespace(e) {
@@ -22,72 +23,97 @@ function _interopNamespace(e) {
 
 const tctx__namespace = /*#__PURE__*/_interopNamespace(tctx);
 
-const measure = (cb, scope, promises) => {
-    const set_error = (error) => {
-        scope.set_context({
-            error,
-        });
-    };
-    return (...args) => {
-        try {
-            var r = cb(...args, scope), is_promise = r instanceof Promise;
-            if (is_promise)
-                promises.push(r.catch(set_error).finally(() => scope.end()));
-            return r;
-        }
-        catch (e) {
-            set_error(e);
-            throw e;
-        }
-        finally {
-            if (is_promise !== true)
-                scope.end();
-        }
-    };
+const set_error = (scope, error) => {
+    scope.set_context({
+        error,
+    });
+};
+const measure = (fn, // TODO: fn doesnt see scope correctly
+scope, promises, ...args) => {
+    try {
+        var r = fn(...args, scope), is_promise = r instanceof Promise;
+        if (is_promise)
+            promises.push(r
+                .catch((e) => void set_error(scope, e))
+                .finally(() => scope.end()));
+        return r;
+    }
+    catch (e) {
+        set_error(scope, e);
+        throw e;
+    }
+    finally {
+        if (is_promise !== true)
+            scope.end();
+    }
+};
+
+// ==> impl
+/**
+ * The default sampler;
+ *
+ * If no parent
+ * ~> sample
+ * if parent was off
+ * ~> never sample
+ * if parent was on
+ * ~> always sample
+ */
+const defaultSampler = (_name, parentId) => {
+    if (!parentId)
+        return true;
+    return tctx__namespace.is_sampled(parentId);
+};
+const sdk_object = {
+    'telemetry.sdk.name': package_json.name,
+    'telemetry.sdk.version': package_json.version,
 };
 const create = (name, options) => {
     const spans = new Set();
     const promises = [];
     const span = (name, parent) => {
-        const id = parent ? parent.child() : tctx__namespace.make(true);
-        let context = {};
+        const should_sample = (options.sampler || defaultSampler)(name, parent, options.context);
+        const id = parent
+            ? parent.child(should_sample)
+            : tctx__namespace.make(should_sample);
         const start = Date.now();
-        let ended = false;
-        // @ts-ignore
-        const $ = (cb) => measure(cb, $, promises)();
+        const span_obj = {
+            id,
+            parent,
+            start,
+            name,
+            context: {},
+        };
+        if (should_sample)
+            spans.add(span_obj);
+        const $ = (cb) => measure(cb, $, promises);
         $.traceparent = id;
         $.fork = (name) => span(name, id);
-        $.measure = (name, cb, ...args) => measure(cb, span(name, id), promises)(...args);
+        $.measure = (name, cb, ...args) => measure(cb, span(name, id), promises, ...args);
         $.set_context = (ctx) => {
             if (typeof ctx === 'function')
-                return void (context = ctx(context));
-            Object.assign(context, ctx);
+                return void (span_obj.context = ctx(span_obj.context));
+            Object.assign(span_obj.context, ctx);
         };
         $.end = () => {
-            if (ended)
+            if (span_obj.end)
                 return void 0;
-            spans.add({
-                id,
-                parent,
-                start,
-                end: Date.now(),
-                name,
-                context,
-            });
-            ended = true;
+            span_obj.end = Date.now();
         };
         return $;
     };
     const root = span(name, typeof options.traceparent === 'string'
         ? tctx__namespace.parse(options.traceparent)
         : undefined);
-    const meEnd = root.end.bind(root);
-    root.end = async () => {
-        meEnd();
-        await Promise.all(promises);
-        return options.collector(spans);
+    return {
+        span: root.fork.bind(root),
+        measure: root.measure.bind(root),
+        async end() {
+            root.end();
+            await Promise.all(promises);
+            return options.exporter(spans, Object.assign(options.context || {}, sdk_object));
+        },
     };
-    return root;
 };
 
 exports.create = create;

package/index.mjs

@@ -1,71 +1,97 @@
+import { name, version } from 'rian/package.json';
 import * as tctx from 'tctx';
 
-const measure = (cb, scope, promises) => {
-    const set_error = (error) => {
-        scope.set_context({
-            error,
-        });
-    };
-    return (...args) => {
-        try {
-            var r = cb(...args, scope), is_promise = r instanceof Promise;
-            if (is_promise)
-                promises.push(r.catch(set_error).finally(() => scope.end()));
-            return r;
-        }
-        catch (e) {
-            set_error(e);
-            throw e;
-        }
-        finally {
-            if (is_promise !== true)
-                scope.end();
-        }
-    };
+const set_error = (scope, error) => {
+    scope.set_context({
+        error,
+    });
+};
+const measure = (fn, // TODO: fn doesnt see scope correctly
+scope, promises, ...args) => {
+    try {
+        var r = fn(...args, scope), is_promise = r instanceof Promise;
+        if (is_promise)
+            promises.push(r
+                .catch((e) => void set_error(scope, e))
+                .finally(() => scope.end()));
+        return r;
+    }
+    catch (e) {
+        set_error(scope, e);
+        throw e;
+    }
+    finally {
+        if (is_promise !== true)
+            scope.end();
+    }
+};
+
+// ==> impl
+/**
+ * The default sampler;
+ *
+ * If no parent
+ * ~> sample
+ * if parent was off
+ * ~> never sample
+ * if parent was on
+ * ~> always sample
+ */
+const defaultSampler = (_name, parentId) => {
+    if (!parentId)
+        return true;
+    return tctx.is_sampled(parentId);
+};
+const sdk_object = {
+    'telemetry.sdk.name': name,
+    'telemetry.sdk.version': version,
 };
 const create = (name, options) => {
     const spans = new Set();
     const promises = [];
     const span = (name, parent) => {
-        const id = parent ? parent.child() : tctx.make(true);
-        let context = {};
+        const should_sample = (options.sampler || defaultSampler)(name, parent, options.context);
+        const id = parent
+            ? parent.child(should_sample)
+            : tctx.make(should_sample);
         const start = Date.now();
-        let ended = false;
-        // @ts-ignore
-        const $ = (cb) => measure(cb, $, promises)();
+        const span_obj = {
+            id,
+            parent,
+            start,
+            name,
+            context: {},
+        };
+        if (should_sample)
+            spans.add(span_obj);
+        const $ = (cb) => measure(cb, $, promises);
         $.traceparent = id;
         $.fork = (name) => span(name, id);
-        $.measure = (name, cb, ...args) => measure(cb, span(name, id), promises)(...args);
+        $.measure = (name, cb, ...args) => measure(cb, span(name, id), promises, ...args);
         $.set_context = (ctx) => {
             if (typeof ctx === 'function')
-                return void (context = ctx(context));
-            Object.assign(context, ctx);
+                return void (span_obj.context = ctx(span_obj.context));
+            Object.assign(span_obj.context, ctx);
         };
         $.end = () => {
-            if (ended)
+            if (span_obj.end)
                 return void 0;
-            spans.add({
-                id,
-                parent,
-                start,
-                end: Date.now(),
-                name,
-                context,
-            });
-            ended = true;
+            span_obj.end = Date.now();
         };
         return $;
     };
     const root = span(name, typeof options.traceparent === 'string'
         ? tctx.parse(options.traceparent)
         : undefined);
-    const meEnd = root.end.bind(root);
-    root.end = async () => {
-        meEnd();
-        await Promise.all(promises);
-        return options.collector(spans);
+    return {
+        span: root.fork.bind(root),
+        measure: root.measure.bind(root),
+        async end() {
+            root.end();
+            await Promise.all(promises);
+            return options.exporter(spans, Object.assign(options.context || {}, sdk_object));
+        },
     };
-    return root;
 };
 
 export { create };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rian",
-	"version": "0.0.2-alpha.10",
+	"version": "0.0.2-alpha.11",
 	"description": "A tracer for the edge",
 	"keywords": [
 		"TODO"
@@ -19,6 +19,14 @@
 			"import": "./index.mjs",
 			"require": "./index.js"
 		},
+		"./exporter.otel.http": {
+			"import": "./exporter.otel.http.mjs",
+			"require": "./exporter.otel.http.js"
+		},
+		"./exporter.zipkin": {
+			"import": "./exporter.zipkin.mjs",
+			"require": "./exporter.zipkin.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"main": "./index.js",
@@ -30,6 +38,7 @@
 		"*.d.ts"
 	],
 	"dependencies": {
+		"flattie": "^1.1.0",
 		"tctx": "^0.0.10"
 	}
 }