graftcode-instrumentation 0.0.0-stage → 1.0.3

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# graftcode-instrumentation (Node.js)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OpenTelemetry instrumentation for Graftcode (Hypertube) calls: client and server spans, W3C trace context propagation, and Hypertube log forwarding.
+
+Hypertube exposes a **broker** (`HypertubeBroker.attach` / `detach`); nothing is monkey-patched. Enabling attaches a broker listener and a log listener; disabling removes them.
+
+## Usage
+
+Register like any other OpenTelemetry instrumentation:
+
+```js
+import { registerInstrumentations } from '@opentelemetry/instrumentation'
+import { GraftcodeInstrumentation } from 'graftcode-instrumentation'
+
+registerInstrumentations({ instrumentations: [new GraftcodeInstrumentation()] })
+```
+
+## Configuration (`GraftcodeInstrumentationConfig`)
+
+| Option | Description |
+|--------|-------------|
+| `enabled` | Default `true`. |
+| `captureBodies` | Record redacted request and response payloads on spans. Defaults to env `HYPERTUBE_TELEMETRY_CAPTURE_BODIES`, otherwise `false`. |
+| `maxBodyLength` | Characters kept per payload, 256–32768. Defaults to `HYPERTUBE_TELEMETRY_BODY_MAX_CHARS`, otherwise `8192`. |
+| `propagateContext` | Send W3C trace context with outgoing calls. Defaults to `HYPERTUBE_TELEMETRY_AUTO_INJECT`, otherwise `true`. |
+| `logLevel` | Lowest Hypertube log level forwarded to OpenTelemetry logs (`trace`, `debug`, `info`, `warning`, `error`, `critical`, `off`). Default `info`. |
+| `ignore` | `(operation) => boolean` — return `true` to skip tracing an operation. |
+| `libraries` | Names the library behind a connection for the `Graft <library> <channel>` dependency name. Map from connection address (e.g. `ws://localhost:9180/ws`) to library name, or a function `(target) => string \| undefined`. Node.js types carry no namespace; without this, the caller falls back to `Graft <runtime> <channel>` unless the call loads the library. |
+
+## Span model
+
+- **Caller:** span name `Graft <library> [version] <channel>` (or runtime fallback), kind `INTERNAL`, attributes `graft.dependency.type` = `Graft`, `graft.dependency.target`, plus Hypertube operation metadata.
+- **Callee:** span name `Service.method` (or `method` for globals), kind `INTERNAL`.
+- Remote failures that return an `Exception` command mark the span failed from that response (not only thrown errors).
+
+## Trace context
+
+- Outgoing: W3C `traceparent` / `tracestate` via `callContext.outgoingHeaders`, plus `traceid` when sampled.
+- Incoming: prefers W3C headers; a Graftcode `traceid` header alone still joins that trace under a synthetic remote parent.
+- A `traceparent` already on the connection is not overridden.
+
+## Library catalog
+
+`LibraryCatalog.record` remembers libraries loaded on a connection (`LoadLibrary`) so later calls can be attributed. `LibraryCatalog.describeTarget` formats `<library> [version] <channel>`. Version is read from local `package.json` when available. Package folder naming rules apply for `package.json`, `index.js`, `main.js`, etc.
+
+## Body capture
+
+When enabled, request/response bodies are JSON-like renderings with redaction and truncation (`hypertube.request.body`, `hypertube.response.body`, `.truncated` when clipped).
+
+## Operations (`resolveOperation`)
+
+Maps Hypertube commands to `GraftOperation`: `name` (`Service.method` or `method`), `service`, `method`, `commandType`. Skips non-member / control commands without a resolvable method name.
+
+## Log bridge
+
+Forwards Hypertube log records to the OpenTelemetry Logs API, correlated with the active span, respecting configured minimum level and redaction on errors.

package/package.json

@@ -1,6 +1,40 @@
 {
-  "name": "graftcode-instrumentation",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "graftcode-instrumentation",
+    "version": "1.0.3",
+    "description": "OpenTelemetry instrumentation for Graftcode (Hypertube) calls in Node.js: client and server spans, W3C trace context propagation and Hypertube log forwarding.",
+    "license": "ISC",
+    "author": "Graftcode S.A.",
+    "type": "module",
+    "main": "./src/index.js",
+    "types": "./src/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./src/index.d.ts",
+            "default": "./src/index.js"
+        }
+    },
+    "files": [
+        "README.md",
+        "src"
+    ],
+    "engines": {
+        "node": ">=20"
+    },
+    "scripts": {
+        "test": "node --test \"test/**/*.test.js\""
+    },
+    "dependencies": {
+        "@opentelemetry/instrumentation": "^0.221.0"
+    },
+    "peerDependencies": {
+        "@opentelemetry/api": "^1.9.0",
+        "hypertube-nodejs-sdk": "*"
+    },
+    "devDependencies": {
+        "@opentelemetry/api": "^1.9.1",
+        "@opentelemetry/sdk-logs": "^0.221.0",
+        "@opentelemetry/sdk-trace-base": "^2.10.0",
+        "@opentelemetry/sdk-trace-node": "^2.10.0",
+        "hypertube-nodejs-sdk": "file:../../../../NewHT/HYPERTUBE/src/js/hypertube-nodejs-sdk"
+    }
+}

package/src/GraftcodeInstrumentation.js

@@ -0,0 +1,116 @@
+import { createRequire } from 'node:module'
+import { context } from '@opentelemetry/api'
+import { InstrumentationBase } from '@opentelemetry/instrumentation'
+import {
+    HypertubeBroker,
+    HypertubeLogger,
+    LogsCommandResolver,
+    LogsLevel,
+    LogsRedactor,
+} from 'hypertube-nodejs-sdk/abstractions'
+import { CallSpan, completeSpans } from './callSpan.js'
+import { resolveInstrumentationOptions } from './graftcodeTelemetrySettings.js'
+
+const { version: PACKAGE_VERSION } = createRequire(import.meta.url)('../package.json')
+
+export const INSTRUMENTATION_NAME = 'Graftcode'
+export const LOGGER_NAME = 'Hypertube'
+
+const SEVERITIES = [
+    [1, 'TRACE'],
+    [5, 'DEBUG'],
+    [9, 'INFO'],
+    [13, 'WARN'],
+    [17, 'ERROR'],
+    [21, 'FATAL'],
+]
+
+export class GraftcodeInstrumentation extends InstrumentationBase {
+    constructor(config = {}) {
+        super(INSTRUMENTATION_NAME, PACKAGE_VERSION, config)
+    }
+
+    init() {
+        return []
+    }
+
+    enable() {
+        if (this._detachFromHypertube) {
+            return
+        }
+
+        const getSettings = () => this._currentSettings()
+        const listener = {
+            onExecute: (callContext, command, connectionData) => {
+                const reported = LogsCommandResolver.resolveForInvoke(command)
+                CallSpan.startInvoke(this.tracer, callContext, reported, connectionData, getSettings())
+            },
+            onResponse: (callContext, response) => {
+                completeSpans(callContext, response, null)
+            },
+            onInvocationError: (callContext, error) => {
+                completeSpans(callContext, null, error)
+            },
+            onProcess: (callContext, command) => {
+                const headers = {}
+                const reported = LogsCommandResolver.resolveForHandle(command, headers)
+                CallSpan.startHandle(this.tracer, callContext, reported, headers, getSettings())
+            },
+            onProcessed: (callContext, response) => {
+                completeSpans(callContext, response, null)
+            },
+            onHandlingError: (callContext, error) => {
+                completeSpans(callContext, null, error)
+            },
+        }
+
+        const logBridge = {
+            isEnabled: (level) => level < LogsLevel.Off && level >= getSettings().logLevel,
+
+            log: (record) => {
+                const [severityNumber, severityText] = SEVERITIES[record.level] ?? SEVERITIES[LogsLevel.Info]
+                const attributes = { ...record.properties }
+
+                if (record.error !== undefined && record.error !== null) {
+                    const error = record.error
+                    attributes['exception.type'] = error instanceof Error ? error.name : typeof error
+                    attributes['exception.message'] = String(
+                        LogsRedactor.redactValue(error instanceof Error ? error.message : String(error)) ?? ''
+                    )
+                    if (error instanceof Error && error.stack) {
+                        attributes['exception.stacktrace'] = LogsRedactor.redactBody(error.stack)
+                    }
+                }
+
+                this.logger.emit({
+                    severityNumber,
+                    severityText,
+                    body: record.message,
+                    attributes,
+                    context: context.active(),
+                })
+            },
+        }
+
+        const detachBroker = HypertubeBroker.attach(listener)
+        const detachLogs = HypertubeLogger.attach(logBridge)
+        this._detachFromHypertube = () => {
+            detachBroker()
+            detachLogs()
+        }
+    }
+
+    disable() {
+        this._detachFromHypertube?.()
+        this._detachFromHypertube = undefined
+    }
+
+    _currentSettings() {
+        const config = this.getConfig()
+        if (config !== this._settingsSource || !this._settings) {
+            this._settingsSource = config
+            this._settings = resolveInstrumentationOptions(config)
+        }
+        return this._settings
+    }
+}

package/src/bodyCapture.js

@@ -0,0 +1,109 @@
+import { LogsRedactor, commandTypeName, isCommand, runtimeNameOf } from 'hypertube-nodejs-sdk/abstractions'
+
+const TRUNCATION_MARKER = '"__truncated__"'
+const MAX_DEPTH = 24
+const CLOSING_COST_PER_LEVEL = 18
+const SCALAR_RESERVE = 32
+
+export function renderBody(command, maxLength) {
+    if (!isCommand(command)) {
+        return undefined
+    }
+
+    const writer = { out: '', max: maxLength, truncated: false }
+    writeCommand(writer, command, 0)
+    return { body: LogsRedactor.redactBody(writer.out), truncated: writer.truncated }
+}
+
+function writeCommand(writer, command, depth) {
+    writer.out += `{"runtime":"${runtimeNameOf(command.runtimeName)}","type":"${commandTypeName(command.commandType)}","payload":[`
+
+    const budget = Math.max(0, writer.max - (depth + 1) * CLOSING_COST_PER_LEVEL - SCALAR_RESERVE)
+    const payload = command.payload
+    let complete = true
+    let hasContent = false
+
+    for (let i = 0; i < payload.length; i++) {
+        if (writer.out.length >= budget) {
+            writer.truncated = true
+            complete = false
+            break
+        }
+        if (hasContent) {
+            writer.out += ','
+        }
+        hasContent = true
+
+        const followsSensitiveKey =
+            i > 0 && typeof payload[i - 1] === 'string' && LogsRedactor.isSensitiveKey(payload[i - 1])
+        if (!writeValue(writer, payload[i], depth + 1, budget, followsSensitiveKey)) {
+            complete = false
+            break
+        }
+    }
+
+    if (!complete) {
+        writer.out += hasContent ? `,${TRUNCATION_MARKER}` : TRUNCATION_MARKER
+    }
+    writer.out += ']}'
+    return complete
+}
+
+function writeValue(writer, value, depth, budget, forceRedact) {
+    if (value === null || value === undefined) {
+        writer.out += 'null'
+        return true
+    }
+    if (depth >= MAX_DEPTH) {
+        writer.truncated = true
+        writer.out += TRUNCATION_MARKER
+        return true
+    }
+    if (isCommand(value)) {
+        return writeCommand(writer, value, depth)
+    }
+    if (forceRedact) {
+        return writeString(writer, LogsRedactor.Placeholder, budget)
+    }
+
+    switch (typeof value) {
+        case 'string':
+            return writeString(writer, LogsRedactor.redactValue(value), budget)
+        case 'boolean':
+            writer.out += String(value)
+            return true
+        case 'number':
+            writer.out += Number.isFinite(value) ? String(value) : `"${value}"`
+            return true
+        case 'bigint':
+            writer.out += value.toString()
+            return true
+    }
+
+    if (value instanceof Uint8Array) {
+        writer.out += `"[bytes:${value.length}]"`
+        return true
+    }
+    return writeString(writer, LogsRedactor.redactValue(format(value)), budget)
+}
+
+function writeString(writer, value, budget) {
+    const encoded = JSON.stringify(value)
+    if (writer.out.length + encoded.length <= budget) {
+        writer.out += encoded
+        return true
+    }
+
+    writer.truncated = true
+    const room = Math.max(0, budget - writer.out.length - 2)
+    writer.out += JSON.stringify(value.slice(0, room))
+    return false
+}
+
+function format(value) {
+    try {
+        return String(value)
+    } catch {
+        return `[unrenderable:${Object.prototype.toString.call(value)}]`
+    }
+}

package/src/callSpan.js

@@ -0,0 +1,257 @@
+import { randomBytes } from 'node:crypto'
+import { SpanKind, SpanStatusCode, TraceFlags, context, isSpanContextValid, propagation, trace } from '@opentelemetry/api'
+import {
+    CommandType,
+    LogsRedactor,
+    commandTypeName,
+    connectionTypeName,
+    isCommand,
+    runtimeNameOf,
+} from 'hypertube-nodejs-sdk/abstractions'
+import { renderBody } from './bodyCapture.js'
+import * as GraftcodeTelemetrySettings from './graftcodeTelemetrySettings.js'
+import { describeTarget, record } from './libraryCatalog.js'
+import { resolveOperation } from './resolveOperation.js'
+
+export const DEPENDENCY_TYPE = 'graft.dependency.type'
+export const DEPENDENCY_TARGET = 'graft.dependency.target'
+export const BRIDGE_DEPENDENCY_TYPE = 'Graft'
+export const REQUEST_BODY = 'hypertube.request.body'
+export const RESPONSE_BODY = 'hypertube.response.body'
+export const REQUEST_BODY_TRUNCATED = 'hypertube.request.body.truncated'
+export const RESPONSE_BODY_TRUNCATED = 'hypertube.response.body.truncated'
+export const TRACE_PARENT_HEADER = 'traceparent'
+export const TRACE_STATE_HEADER = 'tracestate'
+export const TRACE_ID_HEADER = 'traceid'
+
+const SKIP_COMMAND_TYPES = new Set([
+    CommandType.PassByValue,
+    CommandType.RegisterForUpdate,
+    CommandType.ValueForUpdate,
+    CommandType.InvokeDelegate,
+])
+
+export class CallSpan {
+    #span
+    #settings
+    #completed = false
+
+    constructor(span, settings) {
+        this.#span = span
+        this.#settings = settings
+    }
+
+    static startInvoke(tracer, callContext, command, connectionData, settings) {
+        const operation = tryResolveOperation(command, settings)
+        if (!operation) {
+            return null
+        }
+
+        record(command, connectionData)
+        const target = describeTarget(command, connectionData, settings.libraries, operation)
+        const parent = context.active()
+        const span = tracer.startSpan(
+            `Graft ${target}`,
+            {
+                kind: SpanKind.INTERNAL,
+                attributes: invokeAttributes(operation, command, connectionData, target),
+            },
+            parent
+        )
+        const callSpan = new CallSpan(span, settings)
+        callSpan.#pushScope(callContext, parent, span)
+        callSpan.capture(command, REQUEST_BODY, REQUEST_BODY_TRUNCATED)
+
+        if (GraftcodeTelemetrySettings.isAutoInjectEnabled() && !hasOwnTraceparent(connectionData)) {
+            inject(trace.setSpan(parent, span), callContext.outgoingHeaders)
+        }
+
+        return callSpan
+    }
+
+    static startHandle(tracer, callContext, command, headers, settings) {
+        const operation = tryResolveOperation(command, settings)
+        if (!operation) {
+            return null
+        }
+
+        const parent = extractParent(headers)
+        const span = tracer.startSpan(
+            operation.name,
+            { kind: SpanKind.INTERNAL, attributes: handleAttributes(operation, command) },
+            parent
+        )
+        const callSpan = new CallSpan(span, settings)
+        callSpan.#pushScope(callContext, parent, span)
+        callSpan.capture(command, REQUEST_BODY, REQUEST_BODY_TRUNCATED)
+        return callSpan
+    }
+
+    complete(response, error) {
+        if (this.#completed) {
+            return
+        }
+        this.#completed = true
+
+        if (response != null) {
+            this.capture(response, RESPONSE_BODY, RESPONSE_BODY_TRUNCATED)
+        }
+
+        if (error == null) {
+            if (isCommand(response) && response.commandType === CommandType.Exception) {
+                const name = typeof response.payload[2] === 'string' ? response.payload[2] : 'Exception'
+                const message = typeof response.payload[3] === 'string' ? response.payload[3] : ''
+                markFailed(this.#span, name, message)
+            } else {
+                this.#span.setStatus({ code: SpanStatusCode.OK })
+            }
+        } else {
+            const name = error instanceof Error ? error.name : typeof error
+            const message = error instanceof Error ? error.message : String(error)
+            const stack =
+                error instanceof Error && error.stack ? LogsRedactor.redactBody(error.stack) : undefined
+            markFailed(this.#span, name, message, stack)
+        }
+
+        this.#span.end()
+    }
+
+    capture(command, bodyKey, truncatedKey) {
+        if (!this.#span.isRecording() || !GraftcodeTelemetrySettings.isBodyCaptureEnabled()) {
+            return
+        }
+        const rendered = renderBody(command, GraftcodeTelemetrySettings.getBodyMaxCharacters())
+        if (!rendered) {
+            return
+        }
+        this.#span.setAttribute(bodyKey, rendered.body)
+        if (rendered.truncated) {
+            this.#span.setAttribute(truncatedKey, true)
+        }
+    }
+
+    #pushScope(callContext, parent, span) {
+        const active = trace.setSpan(parent, span)
+        callContext.items.push(this)
+        callContext.items.push({
+            wrap(run) {
+                return context.with(active, run)
+            },
+        })
+    }
+}
+
+function tryResolveOperation(command, settings) {
+    if (!isCommand(command) || SKIP_COMMAND_TYPES.has(command.commandType)) {
+        return undefined
+    }
+
+    const operation = resolveOperation(command)
+    if (!operation || settings.ignore?.(operation)) {
+        return undefined
+    }
+
+    if (operation.name.toLowerCase().endsWith('telemetrysetup.initialize')) {
+        return undefined
+    }
+
+    return operation
+}
+
+function invokeAttributes(operation, command, connectionData, target) {
+    const attributes = handleAttributes(operation, command)
+    const connectionType = safe(() => connectionData.connectionType)
+
+    attributes[DEPENDENCY_TYPE] = BRIDGE_DEPENDENCY_TYPE
+    attributes[DEPENDENCY_TARGET] = String(LogsRedactor.redactValue(target) ?? '')
+    attributes['hypertube.target'] = safe(() => LogsRedactor.redactTarget(connectionData.hostname)) ?? ''
+    if (typeof connectionType === 'number') {
+        attributes['hypertube.connection_type'] = connectionTypeName(connectionType)
+    }
+    return attributes
+}
+
+function handleAttributes(operation, command) {
+    return {
+        'hypertube.runtime': runtimeNameOf(command.runtimeName),
+        'hypertube.command_type': commandTypeName(command.commandType),
+        'hypertube.operation': operation.name,
+    }
+}
+
+function markFailed(span, name, message, stack) {
+    const redacted = String(LogsRedactor.redactValue(message) ?? '')
+    span.recordException({ name, message: redacted, stack })
+    span.setAttribute('exception.type', name)
+    if (redacted) {
+        span.setAttribute('exception.message', redacted)
+    }
+    span.setStatus({ code: SpanStatusCode.ERROR, message: redacted })
+}
+
+function inject(active, headers) {
+    propagation.inject(active, headers)
+    const spanContext = trace.getSpanContext(active)
+    if (spanContext && isSpanContextValid(spanContext)) {
+        headers[TRACE_ID_HEADER] = spanContext.traceId
+    }
+}
+
+function extractParent(headers) {
+    const base = context.active()
+    const extracted = propagation.extract(base, headers)
+    const extractedSpan = trace.getSpanContext(extracted)
+    if (extractedSpan && isSpanContextValid(extractedSpan) && extractedSpan !== trace.getSpanContext(base)) {
+        return extracted
+    }
+
+    const traceId = readTraceId(headers[TRACE_ID_HEADER])
+    if (!traceId) {
+        return base
+    }
+    return trace.setSpanContext(base, {
+        traceId,
+        spanId: randomSpanId(),
+        traceFlags: TraceFlags.SAMPLED,
+        isRemote: true,
+    })
+}
+
+function readTraceId(raw) {
+    const hex = raw?.trim().replaceAll('-', '').toLowerCase()
+    return hex && /^[0-9a-f]{32}$/.test(hex) && !/^0+$/.test(hex) ? hex : undefined
+}
+
+function randomSpanId() {
+    let spanId
+    do {
+        spanId = randomBytes(8).toString('hex')
+    } while (/^0+$/.test(spanId))
+    return spanId
+}
+
+function hasOwnTraceparent(connectionData) {
+    try {
+        return TRACE_PARENT_HEADER in connectionData.getHeaders()
+    } catch {
+        return false
+    }
+}
+
+function safe(read) {
+    try {
+        return read()
+    } catch {
+        return undefined
+    }
+}
+
+export function completeSpans(callContext, response, error) {
+    for (let i = callContext.items.length - 1; i >= 0; i--) {
+        const item = callContext.items[i]
+        if (item instanceof CallSpan) {
+            item.complete(response, error)
+            callContext.items.splice(i, 1)
+        }
+    }
+}

package/src/graftcodeTelemetrySettings.js

@@ -0,0 +1,77 @@
+import { LogsLevel, parseLogsLevel } from 'hypertube-nodejs-sdk/abstractions'
+
+export const MINIMUM_BODY_MAX_CHARS = 256
+export const DEFAULT_BODY_MAX_CHARS = 8192
+export const MAXIMUM_BODY_MAX_CHARS = 32768
+
+let autoInject = readFlag('HYPERTUBE_TELEMETRY_AUTO_INJECT', true)
+let captureBodies = readFlag('HYPERTUBE_TELEMETRY_CAPTURE_BODIES', false)
+let bodyMaxCharacters = readBodyMaxChars()
+
+export function isAutoInjectEnabled() {
+    return autoInject
+}
+
+export function setAutoInjectEnabled(value) {
+    autoInject = value
+}
+
+export function isBodyCaptureEnabled() {
+    return captureBodies
+}
+
+export function setBodyCaptureEnabled(value) {
+    captureBodies = value
+}
+
+export function getBodyMaxCharacters() {
+    return bodyMaxCharacters
+}
+
+export function setBodyMaxCharacters(value) {
+    bodyMaxCharacters = clampBodyMaxCharacters(value)
+}
+
+export function clampBodyMaxCharacters(value) {
+    if (value < MINIMUM_BODY_MAX_CHARS) {
+        return MINIMUM_BODY_MAX_CHARS
+    }
+    return Math.min(value, MAXIMUM_BODY_MAX_CHARS)
+}
+
+export function applyInstrumentationConfig(config) {
+    if (config.propagateContext !== undefined) {
+        setAutoInjectEnabled(config.propagateContext)
+    }
+    if (config.captureBodies !== undefined) {
+        setBodyCaptureEnabled(config.captureBodies)
+    }
+    if (config.maxBodyLength !== undefined) {
+        setBodyMaxCharacters(config.maxBodyLength)
+    }
+}
+
+export function resolveInstrumentationOptions(config) {
+    applyInstrumentationConfig(config)
+    return {
+        logLevel: parseLogsLevel(config.logLevel ?? 'info') ?? LogsLevel.Info,
+        ignore: typeof config.ignore === 'function' ? config.ignore : undefined,
+        libraries:
+            typeof config.libraries === 'function' || (config.libraries && typeof config.libraries === 'object')
+                ? config.libraries
+                : undefined,
+    }
+}
+
+function readBodyMaxChars() {
+    const value = Number.parseInt(process.env.HYPERTUBE_TELEMETRY_BODY_MAX_CHARS ?? '', 10)
+    return Number.isFinite(value) ? clampBodyMaxCharacters(value) : DEFAULT_BODY_MAX_CHARS
+}
+
+function readFlag(name, defaultValue) {
+    const value = process.env[name]?.trim().toLowerCase()
+    if (!value) {
+        return defaultValue
+    }
+    return value !== 'false' && value !== '0'
+}

package/src/index.d.ts

@@ -0,0 +1,39 @@
+import type { InstrumentationBase, InstrumentationConfig } from '@opentelemetry/instrumentation'
+
+export interface GraftOperation {
+    name: string
+    service?: string
+    method: string
+    commandType: string
+}
+
+export interface LibraryTarget {
+    target: string
+    channel: string
+    runtime: string
+    service?: string
+    method: string
+}
+
+export type LibraryResolver = Record<string, string> | ((target: LibraryTarget) => string | undefined)
+
+export interface GraftcodeInstrumentationConfig extends InstrumentationConfig {
+    captureBodies?: boolean
+    maxBodyLength?: number
+    propagateContext?: boolean
+    logLevel?: 'trace' | 'debug' | 'info' | 'warning' | 'error' | 'critical' | 'off'
+    ignore?: (operation: GraftOperation) => boolean
+    libraries?: LibraryResolver
+}
+
+export declare const INSTRUMENTATION_NAME: 'Graftcode'
+export declare const LOGGER_NAME: 'Hypertube'
+
+export declare class GraftcodeInstrumentation extends InstrumentationBase<GraftcodeInstrumentationConfig> {
+    constructor(config?: GraftcodeInstrumentationConfig)
+    protected init(): []
+    enable(): void
+    disable(): void
+}
+
+export declare function resolveOperation(command: unknown): GraftOperation | undefined

package/src/index.js

@@ -0,0 +1,2 @@
+export { GraftcodeInstrumentation, INSTRUMENTATION_NAME, LOGGER_NAME } from './GraftcodeInstrumentation.js'
+export { resolveOperation } from './resolveOperation.js'

package/src/libraryCatalog.js

@@ -0,0 +1,189 @@
+import { readFileSync, statSync } from 'node:fs'
+import { basename, dirname, extname, join } from 'node:path'
+import { CommandType, connectionTypeName, isCommand, runtimeNameOf } from 'hypertube-nodejs-sdk/abstractions'
+import { resolveTargetTypeName } from './operationName.js'
+
+const MAX_DEPTH = 32
+const ENTRY_FILE_NAMES = new Set(['index', 'main'])
+
+const librariesByConnection = new Map()
+const versionByPath = new Map()
+
+export function record(command, connectionData) {
+    for (const load of findCommands(command, CommandType.LoadLibrary, 0)) {
+        const path = libraryPath(load)
+        const name = path ? libraryNameFromPath(path) : undefined
+        if (!path || !name) {
+            continue
+        }
+
+        const key = connectionKey(connectionData)
+        let libraries = librariesByConnection.get(key)
+        if (!libraries) {
+            libraries = new Map()
+            librariesByConnection.set(key, libraries)
+        }
+        libraries.set(name.toLowerCase(), { name, version: readVersion(path) })
+    }
+}
+
+export function describeTarget(command, connectionData, configured, operation) {
+    const channel = channelName(connectionData)
+    const library = resolveLibrary(command, connectionData, operation, configured)
+    if (!library) {
+        return `${runtimeNameOf(command.runtimeName)} ${channel}`
+    }
+    return library.version ? `${library.name} ${library.version} ${channel}` : `${library.name} ${channel}`
+}
+
+export function channelName(connectionData) {
+    return typeof connectionData.connectionType === 'number'
+        ? connectionTypeName(connectionData.connectionType).toLowerCase()
+        : 'unknown'
+}
+
+export function resetLibraryCatalog() {
+    librariesByConnection.clear()
+    versionByPath.clear()
+}
+
+function resolveLibrary(command, connectionData, operation, configured) {
+    const named = configuredName(configured, connectionData, command, operation)
+    if (named) {
+        return lookup(connectionData, named) ?? { name: named, version: '' }
+    }
+
+    for (const load of findCommands(command, CommandType.LoadLibrary, 0)) {
+        const path = libraryPath(load)
+        const name = path ? libraryNameFromPath(path) : undefined
+        if (name) {
+            return lookup(connectionData, name) ?? { name, version: '' }
+        }
+    }
+
+    const libraries = librariesByConnection.get(connectionKey(connectionData))
+    const typeName = operation?.service ?? resolveTargetTypeName(command)
+    if (!typeName) {
+        return undefined
+    }
+
+    if (libraries) {
+        let best
+        for (const library of libraries.values()) {
+            if (isTypeOfLibrary(typeName, library.name) && (!best || library.name.length > best.name.length)) {
+                best = library
+            }
+        }
+        if (best) {
+            return best
+        }
+    }
+
+    const separator = typeName.indexOf('.')
+    if (separator > 0) {
+        return { name: typeName.slice(0, separator), version: '' }
+    }
+
+    if (libraries?.size === 1) {
+        return libraries.values().next().value
+    }
+    return undefined
+}
+
+function configuredName(configured, connectionData, command, operation) {
+    if (!configured) {
+        return undefined
+    }
+
+    const target = connectionData.hostname ?? ''
+    let name
+    try {
+        name =
+            typeof configured === 'function'
+                ? configured({
+                      target,
+                      channel: channelName(connectionData),
+                      runtime: runtimeNameOf(command.runtimeName),
+                      service: operation?.service ?? resolveTargetTypeName(command),
+                      method: operation?.method,
+                  })
+                : (configured[target] ?? configured[target.replace(/\/+$/, '')])
+    } catch {
+        return undefined
+    }
+    return typeof name === 'string' && name.trim() ? name.trim() : undefined
+}
+
+function lookup(connectionData, name) {
+    return librariesByConnection.get(connectionKey(connectionData))?.get(name.toLowerCase())
+}
+
+function isTypeOfLibrary(typeName, libraryName) {
+    const type = typeName.toLowerCase()
+    const library = libraryName.toLowerCase()
+    return type === library || type.startsWith(`${library}.`)
+}
+
+function connectionKey(connectionData) {
+    return `${connectionData.connectionType}|${connectionData.hostname ?? ''}`
+}
+
+function findCommands(command, commandType, depth) {
+    if (depth > MAX_DEPTH || !isCommand(command)) {
+        return []
+    }
+
+    const matches = command.commandType === commandType ? [command] : []
+    for (const item of command.payload) {
+        matches.push(...findCommands(item, commandType, depth + 1))
+    }
+    return matches
+}
+
+function libraryPath(load) {
+    for (let i = load.payload.length - 1; i >= 0; i--) {
+        const item = load.payload[i]
+        const text = isCommand(item) && item.commandType === CommandType.Value ? item.payload[0] : item
+        if (typeof text === 'string' && text.trim()) {
+            return text.trim()
+        }
+    }
+    return undefined
+}
+
+function libraryNameFromPath(path) {
+    const trimmed = path.replace(/[\\/]+$/, '')
+    const file = basename(trimmed)
+    if (file.toLowerCase() === 'package.json') {
+        return basename(dirname(trimmed)) || undefined
+    }
+
+    const name = file.slice(0, file.length - extname(file).length) || file
+    if (ENTRY_FILE_NAMES.has(name.toLowerCase()) && /\.[cm]?js$/i.test(file)) {
+        return basename(dirname(trimmed)) || name
+    }
+    return name || undefined
+}
+
+function readVersion(path) {
+    const cached = versionByPath.get(path)
+    if (cached !== undefined) {
+        return cached
+    }
+
+    let version = ''
+    try {
+        const trimmed = path.replace(/[\\/]+$/, '')
+        const packageJson = trimmed.toLowerCase().endsWith('package.json')
+            ? trimmed
+            : statSync(trimmed).isDirectory()
+              ? join(trimmed, 'package.json')
+              : join(dirname(trimmed), 'package.json')
+        const parsed = JSON.parse(readFileSync(packageJson, 'utf8'))
+        version = typeof parsed.version === 'string' ? parsed.version.trim() : ''
+    } catch {
+        version = ''
+    }
+    versionByPath.set(path, version)
+    return version
+}

package/src/operationName.js

@@ -0,0 +1,139 @@
+import { CommandType, isCommand } from 'hypertube-nodejs-sdk/abstractions'
+
+const MAX_DEPTH = 32
+
+export function isBlank(value) {
+    return value == null || String(value).trim() === ''
+}
+
+export function resolve(command) {
+    if (!isCommand(command)) {
+        return undefined
+    }
+
+    switch (command.commandType) {
+        case CommandType.InvokeStaticMethod:
+        case CommandType.InvokeInstanceMethod:
+        case CommandType.InvokeGenericStaticMethod:
+        case CommandType.InvokeGenericMethod:
+        case CommandType.GetStaticField:
+        case CommandType.SetStaticField:
+        case CommandType.GetInstanceField:
+        case CommandType.SetInstanceField:
+        case CommandType.GetStaticMethodAsDelegate:
+        case CommandType.GetInstanceMethodAsDelegate: {
+            const qualified = qualify(
+                resolveTypeNameCore(command.payload[0], 0),
+                resolveText(command.payload[1], 0)
+            )
+            return qualified ?? fallback(command)
+        }
+
+        case CommandType.CreateClassInstance: {
+            const createdType = resolveTypeNameCore(command.payload[0], 0)
+            return createdType == null ? fallback(command) : `${createdType}.ctor`
+        }
+
+        case CommandType.InvokeGlobalFunction:
+        case CommandType.GetGlobalField: {
+            const name = resolveText(command.payload[0], 0)
+            return name ?? fallback(command)
+        }
+
+        default:
+            return fallback(command)
+    }
+}
+
+export function resolveTargetTypeName(command) {
+    if (!isCommand(command)) {
+        return undefined
+    }
+
+    switch (command.commandType) {
+        case CommandType.InvokeStaticMethod:
+        case CommandType.InvokeInstanceMethod:
+        case CommandType.InvokeGenericStaticMethod:
+        case CommandType.InvokeGenericMethod:
+        case CommandType.GetStaticField:
+        case CommandType.SetStaticField:
+        case CommandType.GetInstanceField:
+        case CommandType.SetInstanceField:
+        case CommandType.GetStaticMethodAsDelegate:
+        case CommandType.GetInstanceMethodAsDelegate:
+        case CommandType.CreateClassInstance:
+            return resolveTypeNameCore(command.payload[0], 0)
+
+        case CommandType.GetType:
+            return resolveTypeNameCore(command, 0)
+
+        default:
+            return undefined
+    }
+}
+
+function fallback(command) {
+    return `hypertube.${command.commandType}`
+}
+
+function qualify(typeName, memberName) {
+    if (isBlank(memberName)) {
+        return undefined
+    }
+    return isBlank(typeName) ? memberName : `${typeName}.${memberName}`
+}
+
+function resolveText(payloadItem, depth) {
+    if (depth > MAX_DEPTH) {
+        return undefined
+    }
+    if (typeof payloadItem === 'string') {
+        return payloadItem.trim() || undefined
+    }
+    if (isCommand(payloadItem) && payloadItem.commandType === CommandType.Value) {
+        return resolveText(payloadItem.payload[0], depth + 1)
+    }
+    return undefined
+}
+
+function resolveTypeNameCore(target, depth) {
+    if (depth > MAX_DEPTH || target == null) {
+        return undefined
+    }
+    if (typeof target === 'string') {
+        return target.trim() || undefined
+    }
+    if (!isCommand(target)) {
+        return undefined
+    }
+    return resolveTypeNameFromCommand(target, depth)
+}
+
+function resolveTypeNameFromCommand(command, depth) {
+    switch (command.commandType) {
+        case CommandType.Value:
+            return resolveTypeNameCore(command.payload[0], depth + 1)
+
+        case CommandType.GetType:
+        case CommandType.Cast:
+        case CommandType.CreateNull:
+            for (const item of command.payload) {
+                const name = resolveText(item, depth + 1)
+                if (!isBlank(name)) {
+                    return name
+                }
+            }
+            return undefined
+
+        case CommandType.CreateClassInstance:
+        case CommandType.SetInstanceField:
+        case CommandType.InvokeStaticMethod:
+        case CommandType.InvokeInstanceMethod:
+        case CommandType.GetStaticField:
+        case CommandType.GetInstanceField:
+            return resolveTypeNameCore(command.payload[0], depth + 1)
+
+        default:
+            return undefined
+    }
+}

package/src/resolveOperation.js

@@ -0,0 +1,104 @@
+import { CommandType, LogsRedactor, commandTypeName, isCommand } from 'hypertube-nodejs-sdk/abstractions'
+
+const MAX_DEPTH = 32
+
+const MEMBER_COMMANDS = new Set([
+    CommandType.InvokeStaticMethod,
+    CommandType.InvokeInstanceMethod,
+    CommandType.InvokeGenericStaticMethod,
+    CommandType.InvokeGenericMethod,
+    CommandType.GetStaticField,
+    CommandType.SetStaticField,
+    CommandType.GetInstanceField,
+    CommandType.SetInstanceField,
+    CommandType.GetStaticMethodAsDelegate,
+    CommandType.GetInstanceMethodAsDelegate,
+])
+
+const TYPE_FROM_TARGET_COMMANDS = new Set([
+    CommandType.CreateClassInstance,
+    CommandType.SetInstanceField,
+    CommandType.InvokeStaticMethod,
+    CommandType.InvokeInstanceMethod,
+    CommandType.GetStaticField,
+    CommandType.GetInstanceField,
+])
+
+export function resolveOperation(command) {
+    if (!isCommand(command)) {
+        return undefined
+    }
+
+    let service
+    let method
+
+    if (MEMBER_COMMANDS.has(command.commandType)) {
+        service = resolveTypeName(command.payload[0], 0)
+        method = resolveText(command.payload[1], 0)
+    } else if (command.commandType === CommandType.CreateClassInstance) {
+        service = resolveTypeName(command.payload[0], 0)
+        method = service ? 'ctor' : undefined
+    } else if (
+        command.commandType === CommandType.InvokeGlobalFunction ||
+        command.commandType === CommandType.GetGlobalField
+    ) {
+        method = resolveText(command.payload[0], 0)
+    }
+
+    if (!method) {
+        return undefined
+    }
+
+    service = service ? LogsRedactor.redactValue(service) : undefined
+    method = LogsRedactor.redactValue(method)
+    return {
+        name: service ? `${service}.${method}` : method,
+        service,
+        method,
+        commandType: commandTypeName(command.commandType),
+    }
+}
+
+function resolveText(item, depth) {
+    if (depth > MAX_DEPTH) {
+        return undefined
+    }
+    if (typeof item === 'string') {
+        return item.trim() || undefined
+    }
+    if (isCommand(item) && item.commandType === CommandType.Value) {
+        return resolveText(item.payload[0], depth + 1)
+    }
+    return undefined
+}
+
+function resolveTypeName(target, depth) {
+    if (depth > MAX_DEPTH || target == null) {
+        return undefined
+    }
+    if (typeof target === 'string') {
+        return target.trim() || undefined
+    }
+    if (!isCommand(target)) {
+        return undefined
+    }
+
+    switch (target.commandType) {
+        case CommandType.Value:
+            return resolveTypeName(target.payload[0], depth + 1)
+        case CommandType.GetType:
+        case CommandType.Cast:
+        case CommandType.CreateNull:
+            for (const item of target.payload) {
+                const name = resolveText(item, depth + 1)
+                if (name) {
+                    return name
+                }
+            }
+            return undefined
+        default:
+            return TYPE_FROM_TARGET_COMMANDS.has(target.commandType)
+                ? resolveTypeName(target.payload[0], depth + 1)
+                : undefined
+    }
+}