@toa.io/core 1.0.0-alpha.243 → 1.0.0-alpha.246

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/core",
-  "version": "1.0.0-alpha.243",
+  "version": "1.0.0-alpha.246",
   "description": "Toa Core",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -22,10 +22,10 @@
   "dependencies": {
     "@rsql/parser": "1.2.4",
     "@toa.io/generic": "1.0.0-alpha.225",
-    "@toa.io/yaml": "1.0.0-alpha.225",
+    "@toa.io/yaml": "1.0.0-alpha.246",
     "error-value": "0.3.0",
-    "openspan": "1.0.0-alpha.173",
+    "openspan": "1.0.0-alpha.246",
     "uuid": "11.1.1"
   },
-  "gitHead": "743e8060d35ca750f70487c04aef9698591c5edd"
+  "gitHead": "d6ee2a7246c64a44c50c28fadcfd1e27aaf137cb"
 }

package/src/call.js

@@ -1,6 +1,7 @@
 'use strict'
 
 const { Readable } = require('node:stream')
+const { current, encode } = require('openspan')
 const { Connector } = require('./connector')
 const { Err } = require('error-value')
 
@@ -25,6 +26,11 @@ class Call extends Connector {
     // avoid validation on the recipient's side
     request.authentic = true
 
+    const context = current()
+
+    if (context !== undefined)
+      request.telemetry = encode(context)
+
     const reply = await this.#transmitter.request(request)
 
     if (reply === null) return null

package/src/component.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const assert = require('node:assert')
-const { console } = require('openspan')
+const { console, current, decode, run } = require('openspan')
 const { Connector } = require('./connector')
 
 class Component extends Connector {
@@ -10,6 +10,9 @@ class Component extends Connector {
   /** @protected */
   operations
 
+  /** @protected */
+  kind = 'server'
+
   constructor (locator, operations) {
     super()
 
@@ -23,15 +26,39 @@ class Component extends Connector {
     assert.ok(endpoint in this.operations,
       `Endpoint '${endpoint}' is not provided by '${this.locator.id}'`)
 
-    const reply = await this.operations[endpoint].invoke(request)
+    // if the request carries no telemetry, the trace starts here
+    const remote = request?.telemetry === undefined ? null : decode(request.telemetry)
+    const task = () => this.process(endpoint, request)
+
+    if (remote === null)
+      return task()
+    else
+      return run(remote, task)
+  }
+
+  /** @private */
+  async process (endpoint, request) {
+    const options = { name: `${this.locator.id}.${endpoint}`, kind: this.kind }
+
+    // the server span is emitted by the component itself,
+    // while the client span belongs to the calling service and inherits it from the context
+    if (this.kind === 'server')
+      options.service = this.locator.id
+
+    return console.span(options, async () => {
+      const reply = await this.operations[endpoint].invoke(request)
+
+      if (reply?.exception !== undefined) {
+        current().status = 'error'
 
-    if (reply?.exception !== undefined)
-      console.error('Failed to execute operation', {
-        endpoint: `${this.locator.id}.${endpoint}`,
-        exception: reply.exception
-      })
+        console.error('Failed to execute operation', {
+          endpoint: `${this.locator.id}.${endpoint}`,
+          exception: reply.exception
+        })
+      }
 
-    return reply
+      return reply
+    })
   }
 }
 

package/src/connector.js

@@ -85,10 +85,18 @@ class Connector {
 
     this.#disconnecting = undefined
 
-    this.#connecting = (async () => {
+    const work = async () => {
       await Promise.all(this.#dependencies.map((connector) => connector.connect()))
       await this.open()
-    })()
+    }
+
+    // anonymous grouping nodes are not worth a span
+    this.#connecting = TRACE_BOOT && this.constructor.name !== 'Connector'
+      ? console.span({
+        name: `connect ${this.constructor.name}`,
+        attributes: { id: this.locator?.id ?? this.id }
+      }, work)
+      : work()
 
     try {
       await this.#connecting
@@ -177,5 +185,6 @@ class Connector {
 }
 
 const DELAY = 5000
+const TRACE_BOOT = process.env.TOA_BOOT_TRACE === '1'
 
 exports.Connector = Connector

package/src/event.js

@@ -1,5 +1,6 @@
 'use strict'
 
+const { console, current, encode } = require('openspan')
 const { Connector } = require('./connector')
 
 /**
@@ -12,11 +13,15 @@ class Event extends Connector {
   #conditioned
   #subjective
 
+  /** @type {string} */
+  #label
+
   constructor (definition, emitter, bridge = undefined) {
     super()
 
     this.#conditioned = definition.conditioned
     this.#subjective = definition.subjective
+    this.#label = definition.label ?? 'event'
     this.#emitter = emitter
     this.#bridge = bridge
 
@@ -32,7 +37,20 @@ class Event extends Connector {
       /** @type {toa.core.Message} */
       const message = { payload }
 
-      await this.#emitter.emit(message)
+      const options = {
+        name: `${this.#label} publish`,
+        kind: 'producer',
+        attributes: { 'messaging.destination.name': this.#label }
+      }
+
+      await console.span(options, async () => {
+        const context = current()
+
+        if (context !== undefined)
+          message.telemetry = encode(context)
+
+        await this.#emitter.emit(message)
+      })
     }
   }
 }

package/src/receiver.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const { console } = require('openspan')
+const { console, decode, run } = require('openspan')
 const { add } = require('@toa.io/generic')
 const { Connector } = require('./connector')
 
@@ -17,6 +17,12 @@ class Receiver extends Connector {
   /** @type {string} */
   #endpoint
 
+  /** @type {string} */
+  #label
+
+  /** @type {string} */
+  #destination
+
   /** @type {unknown[]} */
   #arguments
 
@@ -32,6 +38,8 @@ class Receiver extends Connector {
     this.#conditioned = conditioned
     this.#adaptive = adaptive
     this.#endpoint = operation
+    this.#label = definition.label ?? operation
+    this.#destination = definition.destination ?? this.#label
     this.#arguments = definition.arguments
 
     this.#local = local
@@ -43,7 +51,7 @@ class Receiver extends Connector {
 
   /** @hot */
   async receive (message) {
-    const { payload, ...extensions } = message
+    const { payload, telemetry, ...extensions } = message
 
     if (this.#conditioned && await this.#bridge.condition(payload) === false) return
 
@@ -51,17 +59,51 @@ class Receiver extends Connector {
 
     add(request, extensions)
 
-    try {
-      await this.#local.invoke(this.#endpoint, request)
-    } catch (error) {
-      console.error('Receiver error', { 
-        component: this.#local.locator.id, 
-        endpoint: this.#endpoint,
-        error
-       })
+    // continue the trace from the producer span
+    const remote = telemetry === undefined ? null : decode(telemetry)
+    const task = () => this.#process(request)
 
-      throw error
+    if (remote === null)
+      await task()
+    else
+      await run(remote, task)
+  }
+
+  async #process (request) {
+    /*
+     * The delivery span is created on behalf of the messaging destination, so that
+     * each consumer forms its own complete producer/consumer pair, and service graphs
+     * display fan-out correctly: producer -> destination -> each consumer
+     * (Tempo pairs spans one-to-one, thus multiple consumers can not pair
+     * with a single producer span, see grafana/tempo#5408)
+     */
+    const delivery = {
+      name: `${this.#label} deliver`,
+      kind: 'producer',
+      service: this.#destination,
+      attributes: { 'messaging.destination.name': this.#destination }
+    }
+
+    const options = {
+      name: `${this.#label} process`,
+      kind: 'consumer',
+      service: this.#local.locator.id,
+      attributes: { 'messaging.destination.name': this.#destination }
     }
+
+    return console.span(delivery, async () => console.span(options, async () => {
+      try {
+        await this.#local.invoke(this.#endpoint, request)
+      } catch (error) {
+        console.error('Receiver error', {
+          component: this.#local.locator.id,
+          endpoint: this.#endpoint,
+          error
+        })
+
+        throw error
+      }
+    }))
   }
 
   async #request (payload) {

package/src/remote.js

@@ -4,6 +4,8 @@ const assert = require('node:assert')
 const { Component } = require('./component')
 
 class Remote extends Component {
+  kind = 'client'
+
   explain (endpoint) {
     assert.ok(endpoint in this.operations,
       `Endpoint '${endpoint}' is not provided by '${this.locator.id}'`)

package/test/event.test.js

@@ -41,7 +41,7 @@ describe('condition', () => {
       await emit()
 
       const payload = await fixtures.bridge.payload.mock.results[0].value
-      const message = { payload }
+      const message = { payload, telemetry: expect.any(String) }
       expect(fixtures.binding.emit).toHaveBeenCalledWith(message)
     })
 
@@ -71,7 +71,7 @@ describe('condition', () => {
       expect(fixtures.bridge.condition).not.toHaveBeenCalledWith()
 
       const payload = await fixtures.bridge.payload.mock.results[0].value
-      const message = { payload }
+      const message = { payload, telemetry: expect.any(String) }
 
       expect(fixtures.binding.emit).toHaveBeenCalledWith(message)
     })
@@ -84,7 +84,7 @@ describe('payload', () => {
       await emit()
 
       const payload = await fixtures.bridge.payload.mock.results[0].value
-      const message = { payload }
+      const message = { payload, telemetry: expect.any(String) }
 
       expect(fixtures.binding.emit).toHaveBeenCalledWith(message)
     })
@@ -110,7 +110,7 @@ describe('payload', () => {
       await emit()
 
       const payload = fixtures.event.state
-      const message = { payload }
+      const message = { payload, telemetry: expect.any(String) }
 
       expect(fixtures.binding.emit).toHaveBeenCalledWith(message)
     })

package/test/receiver.fixtures.js

@@ -9,6 +9,7 @@ const definition = /** @type {toa.norm.component.Receiver} */ {
 }
 
 const local = /** @type {toa.core.Component} */ {
+  locator: { id: 'default.dummy' },
   invoke: jest.fn()
 }
 

package/types/message.d.ts

@@ -1,3 +1,4 @@
 export interface Message<T = any> {
   payload: T
+  telemetry?: string // W3C traceparent
 }

package/types/request.d.ts

@@ -18,6 +18,7 @@ export interface Request {
   query?: Query
   authentic?: boolean
   task?: boolean
+  telemetry?: string // W3C traceparent
 }
 
 export interface Reply {