@hue-run/sdk 0.21.0 → 0.22.0

package/dist/cli/import-formats/jaeger.js

@@ -0,0 +1,266 @@
+import { ConversionError, isObject, OTLP_SPANS, OtlpTraceCollector, } from "../traces-import-convert.js";
+import { otelTraceKey, OtelSpanCollector, unsigned } from "./otel-spans.js";
+import { readRecords } from "./rows.js";
+const object = (value) => isObject(value) ? value : undefined;
+/** The OTLP traces of an API v3 answer or stream line, when it holds any. */
+function v3Traces(value) {
+    const result = object(object(value)?.result);
+    if (!result)
+        return undefined;
+    if (Array.isArray(result.resourceSpans) || Array.isArray(result.resource_spans))
+        return result;
+    const spans = object(result.spans);
+    if (spans && (Array.isArray(spans.resourceSpans) || Array.isArray(spans.resource_spans)))
+        return spans;
+    return undefined;
+}
+const hasOnly = (value, key) => Object.keys(value).length === 1 && key in value;
+/** A stream's closing line, `{"end": true}`. */
+const isEnd = (value) => {
+    const line = object(value);
+    return line !== undefined && hasOnly(line, "end") && line.end === true;
+};
+/** A gateway error, `{"error": {"httpCode": …, "message": …}}`. */
+const gatewayError = (value) => {
+    const line = object(value);
+    const error = object(line?.error);
+    return line && hasOnly(line, "error") && error && typeof error.httpCode === "number"
+        ? error
+        : undefined;
+};
+export const jaegerApiV3 = {
+    id: "jaeger_api_v3",
+    manifestFormat: "otlp_json",
+    detect: (value) => v3Traces(value) !== undefined || isEnd(value) || gatewayError(value) !== undefined,
+    convert(value, context) {
+        const error = gatewayError(value);
+        if (error)
+            throw new ConversionError(`a Jaeger API error${typeof error.message === "string" ? `: ${error.message}` : ""}`);
+        const traces = v3Traces(value);
+        if (!traces)
+            return;
+        const collector = context.collector(() => new OtlpTraceCollector(), OTLP_SPANS);
+        for (const refusal of collector.add([traces], context.source.digest, jaegerApiV3.id))
+            context.refuse(refusal.reason, refusal.traceId);
+    },
+};
+const isSpan = (value) => isObject(value) &&
+    typeof value.spanID === "string" &&
+    typeof value.operationName === "string" &&
+    "startTime" in value;
+const isTrace = (value) => isObject(value) && Array.isArray(value.spans) && value.spans.some(isSpan);
+/** The traces a value holds: a `{data: […]}` answer, one trace, or one span with its process. */
+function tracesOf(value) {
+    const document = object(value);
+    if (!document)
+        return undefined;
+    if (Array.isArray(document.data) && document.data.some(isTrace))
+        return document.data.map((trace) => object(trace) ?? {});
+    if (isTrace(document))
+        return [document];
+    if (isSpan(document) && typeof document.traceID === "string" && object(document.process))
+        return [{ traceID: document.traceID, spans: [document] }];
+    return undefined;
+}
+/** A tag's typed value as OTLP: Jaeger writes an int64 past 2^53 as its decimal text and binary
+ * as base64; the embedded-process form writes every value as text. */
+function tagValue(tag) {
+    const value = tag.value;
+    switch (tag.type) {
+        case "string":
+            return { stringValue: typeof value === "string" ? value : JSON.stringify(value) };
+        case "bool":
+            return { boolValue: value === true || value === "true" };
+        case "int64":
+            if (typeof value === "number" && Number.isSafeInteger(value))
+                return { intValue: String(value) };
+            if (typeof value === "string" && /^-?\d+$/.test(value))
+                return { intValue: value };
+            break;
+        case "float64":
+            if (typeof value === "number")
+                return { doubleValue: value };
+            if (typeof value === "string" && value.trim() && Number.isFinite(Number(value)))
+                return { doubleValue: Number(value) };
+            break;
+        case "binary":
+            if (typeof value === "string")
+                return { bytesValue: value };
+            break;
+        case undefined:
+            if (typeof value === "string")
+                return { stringValue: value };
+            if (typeof value === "boolean")
+                return { boolValue: value };
+            if (typeof value === "number")
+                return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+            break;
+    }
+    throw new ConversionError(`tag ${String(tag.key)} has a value that is not its type`);
+}
+function tags(value, what) {
+    if (value === undefined || value === null)
+        return new Map();
+    if (!Array.isArray(value))
+        throw new ConversionError(`${what} is not a list`);
+    const map = new Map();
+    for (const item of value) {
+        const tag = object(item);
+        if (!tag || typeof tag.key !== "string")
+            throw new ConversionError(`${what} holds no key`);
+        map.set(tag.key, tagValue(tag));
+    }
+    return map;
+}
+const attributesOf = (map) => [...map].map(([key, value]) => ({ key, value }));
+const textOf = (value) => typeof value?.stringValue === "string" ? value.stringValue : undefined;
+/** Removes a tag and returns its text. */
+const take = (map, key) => {
+    const value = textOf(map.get(key));
+    if (value !== undefined)
+        map.delete(key);
+    return value;
+};
+const KINDS = {
+    internal: 1,
+    server: 2,
+    client: 3,
+    producer: 4,
+    consumer: 5,
+};
+/** Microseconds as nanoseconds; undefined when absent, refused when malformed. */
+function micros(value, what) {
+    if (value === undefined || value === null)
+        return undefined;
+    const count = unsigned(value);
+    if (count === undefined)
+        throw new ConversionError(`${what} is not a count of microseconds`);
+    return count * 1000n;
+}
+function readSpan(span, trace, context, collector) {
+    const traceId = typeof span.traceID === "string" ? span.traceID : trace.traceID;
+    if (typeof traceId !== "string" || !traceId)
+        throw new ConversionError("a span without a traceID");
+    const { spanID, operationName } = span;
+    if (!isSpan(span) || typeof spanID !== "string" || typeof operationName !== "string")
+        throw new ConversionError("a record that is not a Jaeger span");
+    const key = otelTraceKey(traceId);
+    const references = span.references ?? [];
+    if (!Array.isArray(references))
+        throw new ConversionError("references is not a list");
+    const refs = references.map((item) => {
+        const ref = object(item);
+        if (!ref || typeof ref.spanID !== "string" || !ref.spanID)
+            throw new ConversionError("a reference without a spanID");
+        const refTrace = typeof ref.traceID === "string" && ref.traceID ? ref.traceID : traceId;
+        return {
+            type: ref.refType,
+            traceId: refTrace,
+            spanId: ref.spanID,
+            same: otelTraceKey(refTrace) === key,
+        };
+    });
+    const parent = refs.find((ref) => ref.same && ref.type === "CHILD_OF") ??
+        refs.find((ref) => ref.same && ref.type === "FOLLOWS_FROM");
+    const legacyParent = typeof span.parentSpanID === "string" && !/^0*$/.test(span.parentSpanID)
+        ? span.parentSpanID
+        : undefined;
+    const attributes = tags(span.tags, "tags");
+    const kind = take(attributes, "span.kind");
+    let status;
+    const error = attributes.get("error");
+    if (error?.boolValue === true) {
+        attributes.delete("error");
+        const message = take(attributes, "otel.status_description");
+        status = { code: 2, ...(message ? { message } : {}) };
+    }
+    const code = take(attributes, "otel.status_code");
+    if (code !== undefined && !status) {
+        const message = take(attributes, "otel.status_description");
+        const upper = code.toUpperCase();
+        status = {
+            code: upper === "OK" ? 1 : upper === "ERROR" ? 2 : 0,
+            ...(message ? { message } : {}),
+        };
+    }
+    const scopeName = take(attributes, "otel.scope.name") ?? take(attributes, "otel.library.name");
+    const scopeVersion = take(attributes, "otel.scope.version") ?? take(attributes, "otel.library.version");
+    const traceState = take(attributes, "w3c.tracestate");
+    const processes = object(trace.processes);
+    const process = object(span.process) ??
+        (typeof span.processID === "string" && processes
+            ? object(processes[span.processID])
+            : undefined);
+    const resource = tags(process?.tags, "process tags");
+    if (typeof process?.serviceName === "string" && process.serviceName)
+        resource.set("service.name", { stringValue: process.serviceName });
+    const logs = span.logs ?? [];
+    if (!Array.isArray(logs))
+        throw new ConversionError("logs is not a list");
+    const start = micros(span.startTime, "startTime");
+    if (start === 0n)
+        throw new ConversionError("startTime is zero");
+    const duration = micros(span.duration, "duration");
+    const flags = unsigned(span.flags);
+    const otelSpan = {
+        traceId,
+        spanKey: spanID,
+        ...(parent ? { parentKey: parent.spanId } : legacyParent ? { parentKey: legacyParent } : {}),
+        name: operationName,
+        kind: kind !== undefined ? (KINDS[kind] ?? 0) : 0,
+        ...(traceState ? { traceState } : {}),
+        ...(flags !== undefined && flags <= 0xffffffffn ? { flags: Number(flags) } : {}),
+        ...(start !== undefined ? { start } : {}),
+        ...(start !== undefined && duration !== undefined ? { end: start + duration } : {}),
+        attributes: attributesOf(attributes),
+        events: logs.map((item) => {
+            const log = object(item);
+            if (!log)
+                throw new ConversionError("a log that is not an object");
+            const fields = tags(log.fields, "log fields");
+            const name = take(fields, "event") ?? "";
+            const time = micros(log.timestamp, "a log timestamp");
+            return { name, ...(time ? { time } : {}), attributes: attributesOf(fields) };
+        }),
+        links: refs
+            .filter((ref) => ref !== parent)
+            .map((ref) => ({
+            traceId: ref.traceId,
+            spanKey: ref.spanId,
+            attributes: [
+                {
+                    key: "opentracing.ref_type",
+                    value: { stringValue: ref.type === "FOLLOWS_FROM" ? "follows_from" : "child_of" },
+                },
+            ],
+        })),
+        ...(status ? { status } : {}),
+        resource: attributesOf(resource),
+        ...(scopeName
+            ? { scope: { name: scopeName, ...(scopeVersion ? { version: scopeVersion } : {}) } }
+            : {}),
+        record: span,
+    };
+    collector.add(otelSpan, context.source.digest);
+}
+export const jaeger = {
+    id: "jaeger",
+    manifestFormat: "otlp_json",
+    detect: (value) => tracesOf(value) !== undefined,
+    convert(value, context) {
+        const collector = context.collector(() => new OtelSpanCollector("jaeger"));
+        const records = (tracesOf(value) ?? []).flatMap((trace) => {
+            const spans = Array.isArray(trace.spans) ? trace.spans : [trace];
+            return spans.map((span) => ({ span, trace }));
+        });
+        readRecords(context, records, ({ span, trace }) => {
+            const traceId = object(span)?.traceID ?? trace.traceID;
+            return typeof traceId === "string" && traceId ? otelTraceKey(traceId) : undefined;
+        }, ({ span, trace }) => {
+            const record = object(span);
+            if (!record)
+                throw new ConversionError("a span that is not an object");
+            readSpan(record, trace, context, collector);
+        });
+    },
+};

package/dist/cli/import-formats/langfuse.d.ts

@@ -0,0 +1,7 @@
+import type { ImportAdapter } from "./adapter.js";
+/** Hue's documented observation list: a list page (`data`) or the native `observations`
+ * envelope, every record an observation, converted as Hue's own reader converts it. */
+export declare const langfuseObservations: ImportAdapter;
+/** Langfuse's own exports, from its API, UI downloads and blob storage (see the top of this
+ * file), as canonical rows. */
+export declare const langfuse: ImportAdapter;