@platformatic/itc 3.52.4 → 3.53.0

package/lib/index.d.ts

@@ -1,3 +1,4 @@
+import type { Context } from '@opentelemetry/api'
 import { EventEmitter } from 'node:events'
 import { MessagePort } from 'node:worker_threads'
 
@@ -10,6 +11,22 @@ export interface ITCConstructorOptions {
   throwOnMissingHandler?: boolean
 }
 
+export interface OutgoingMessagingSpanOptions {
+  telemetryContext?: Context
+  telemetryMetadata?: Record<string, string>
+}
+
+export interface OutgoingMessagingSpan {
+  meta: {
+    mode: string
+    sourceApplication?: string
+    targetApplication?: string
+    telemetry: Record<string, string>
+  } | null
+  run<T>(callback: () => T): T
+  end(error?: Error | null): void
+}
+
 export class ITC extends EventEmitter {
   constructor (options: ITCConstructorOptions)
 
@@ -20,3 +37,29 @@ export class ITC extends EventEmitter {
   listen (): void
   close (): void
 }
+
+export function initializeITCTelemetry (): Promise<any>
+
+export function startOutgoingMessagingSpan (
+  mode: string,
+  sourceApplication: string,
+  targetApplication: string,
+  messageName: string,
+  options?: OutgoingMessagingSpanOptions
+): OutgoingMessagingSpan | null
+
+export function startOutgoingMessagingSpanSync (
+  mode: string,
+  sourceApplication: string,
+  targetApplication: string,
+  messageName: string,
+  options?: OutgoingMessagingSpanOptions
+): OutgoingMessagingSpan | null
+
+export function traceIncomingMessagingHandler (
+  applicationId: string,
+  messageName: string,
+  handler: Handler,
+  data: any,
+  handlerContext?: Record<string, any>
+): any

package/lib/index.js

@@ -49,18 +49,24 @@ export function parseResponse (response) {
   return response
 }
 
-export function generateRequest (name, data) {
+export function generateRequest (name, data, meta) {
   if (typeof name !== 'string') {
     throw new RequestNameIsNotString(name.toString())
   }
 
-  return {
+  const request = {
     type: PLT_ITC_REQUEST_TYPE,
     version: PLT_ITC_VERSION,
     reqId: randomUUID(),
     name,
     data
   }
+
+  if (typeof meta !== 'undefined') {
+    request.meta = meta
+  }
+
+  return request
 }
 
 export function generateResponse (request, error, data) {
@@ -74,13 +80,19 @@ export function generateResponse (request, error, data) {
   }
 }
 
-export function generateNotification (name, data) {
-  return {
+export function generateNotification (name, data, meta) {
+  const notification = {
     type: PLT_ITC_NOTIFICATION_TYPE,
     version: PLT_ITC_VERSION,
     name,
     data
   }
+
+  if (typeof meta !== 'undefined') {
+    notification.meta = meta
+  }
+
+  return notification
 }
 
 export function generateUnhandledErrorResponse (error) {
@@ -298,7 +310,7 @@ export class ITC extends EventEmitter {
     try {
       this._enableKeepAlive()
 
-      const request = generateRequest(name, message)
+      const request = generateRequest(name, message, options?.meta)
       this._send(request, options)
 
       const promiseWithResolvers = Promise.withResolvers()
@@ -317,7 +329,7 @@ export class ITC extends EventEmitter {
   }
 
   notify (name, message, options) {
-    this._send(generateNotification(name, message), options)
+    this._send(generateNotification(name, message, options?.meta), options)
   }
 
   handle (message, handler) {
@@ -471,3 +483,4 @@ export class ITC extends EventEmitter {
 }
 
 export * as errors from './errors.js'
+export * from './telemetry.js'

package/lib/telemetry.js

@@ -0,0 +1,220 @@
+import { ROOT_CONTEXT, SpanKind, SpanStatusCode, context, propagation, trace } from '@opentelemetry/api'
+
+let tracer = null
+let telemetryInitialization = null
+
+function createMessagingSpanName (type, application, messageName) {
+  return `ITC ${type} ${application}.${messageName}`
+}
+
+function createMessagingAttributes ({ mode, sourceApplication, targetApplication, messageName }) {
+  const attributes = {
+    'messaging.system': 'platformatic-itc',
+    'messaging.operation': mode,
+    'messaging.message.name': messageName
+  }
+
+  if (targetApplication) {
+    attributes['messaging.destination.name'] = targetApplication
+    attributes['platformatic.messaging.target'] = targetApplication
+  }
+
+  if (sourceApplication) {
+    attributes['platformatic.messaging.source'] = sourceApplication
+  }
+
+  return attributes
+}
+
+function createOutgoingMessagingMeta (mode, sourceApplication, targetApplication, telemetryMetadata) {
+  if (!telemetryMetadata || Object.keys(telemetryMetadata).length === 0) {
+    return null
+  }
+
+  return {
+    mode,
+    sourceApplication,
+    targetApplication,
+    telemetry: telemetryMetadata
+  }
+}
+
+function setSpanError (span, error) {
+  span.setAttributes({
+    'error.name': error.name,
+    'error.message': error.message,
+    'error.stack': error.stack
+  })
+
+  span.setStatus({
+    code: SpanStatusCode.ERROR,
+    message: error.message
+  })
+}
+
+function endSpan (span, error) {
+  if (error) {
+    setSpanError(span, error)
+  } else {
+    span.setStatus({ code: SpanStatusCode.OK })
+  }
+
+  span.end()
+}
+
+function getTracer () {
+  if (tracer) {
+    return tracer
+  }
+
+  const tracerProvider = globalThis.platformatic?.tracerProvider
+  if (!tracerProvider) {
+    return null
+  }
+
+  tracer = tracerProvider.getTracer('@platformatic/itc')
+  return tracer
+}
+
+export function initializeITCTelemetry () {
+  if (telemetryInitialization) {
+    return telemetryInitialization
+  }
+
+  telemetryInitialization = Promise.resolve(globalThis.platformatic?.telemetryReady)
+    .catch(() => {
+      // Ignore telemetry initialization failures and fall back to untraced messaging.
+    })
+    .then(() => getTracer())
+
+  return telemetryInitialization
+}
+
+function createNoopOutgoingTelemetry (mode, sourceApplication, targetApplication, telemetryMetadata) {
+  const meta = createOutgoingMessagingMeta(mode, sourceApplication, targetApplication, telemetryMetadata)
+
+  if (!meta) {
+    return null
+  }
+
+  return {
+    meta,
+    run (callback) {
+      return callback()
+    },
+    end () {}
+  }
+}
+
+function getParentContext (telemetryContext, telemetryMetadata) {
+  if (telemetryContext) {
+    return telemetryContext
+  }
+
+  if (telemetryMetadata && Object.keys(telemetryMetadata).length > 0) {
+    return propagation.extract(ROOT_CONTEXT, telemetryMetadata)
+  }
+
+  return context.active()
+}
+
+function createOutgoingMessagingSpan (tracer, mode, sourceApplication, targetApplication, messageName, options = {}) {
+  const parentContext = getParentContext(options.telemetryContext, options.telemetryMetadata)
+  const spanType = mode === 'notify' ? 'notify' : 'send'
+  const spanKind = mode === 'notify' ? SpanKind.PRODUCER : SpanKind.CLIENT
+  const span = tracer.startSpan(
+    createMessagingSpanName(spanType, targetApplication, messageName),
+    {
+      kind: spanKind,
+      attributes: createMessagingAttributes({
+        mode,
+        sourceApplication,
+        targetApplication,
+        messageName
+      })
+    },
+    parentContext
+  )
+
+  const spanContext = trace.setSpan(parentContext, span)
+  const telemetryMetadata = {}
+  propagation.inject(spanContext, telemetryMetadata)
+
+  return {
+    meta: createOutgoingMessagingMeta(mode, sourceApplication, targetApplication, telemetryMetadata),
+    run (callback) {
+      return context.with(spanContext, callback)
+    },
+    end (error) {
+      endSpan(span, error)
+    }
+  }
+}
+
+export function startOutgoingMessagingSpan (mode, sourceApplication, targetApplication, messageName, options = {}) {
+  const activeTracer = getTracer()
+  if (!activeTracer) {
+    return createNoopOutgoingTelemetry(mode, sourceApplication, targetApplication, options.telemetryMetadata)
+  }
+
+  return createOutgoingMessagingSpan(activeTracer, mode, sourceApplication, targetApplication, messageName, options)
+}
+
+export function startOutgoingMessagingSpanSync (mode, sourceApplication, targetApplication, messageName, options = {}) {
+  return startOutgoingMessagingSpan(mode, sourceApplication, targetApplication, messageName, options)
+}
+
+export function traceIncomingMessagingHandler (applicationId, messageName, handler, data, handlerContext = {}) {
+  const activeTracer = getTracer()
+  if (!activeTracer) {
+    return handler(data, handlerContext)
+  }
+
+  const request = handlerContext.message ?? {}
+  const metadata = request.meta ?? {}
+  const mode = handlerContext.notification ? 'notify' : metadata.mode ?? 'send'
+  const sourceApplication = metadata.sourceApplication
+  const telemetryCarrier = metadata.telemetry ?? {}
+  const parentContext = propagation.extract(ROOT_CONTEXT, telemetryCarrier)
+  const spanType = handlerContext.notification ? 'consume' : 'handle'
+  const spanKind = handlerContext.notification ? SpanKind.CONSUMER : SpanKind.SERVER
+  const span = activeTracer.startSpan(
+    createMessagingSpanName(spanType, sourceApplication ?? 'unknown', messageName),
+    {
+      kind: spanKind,
+      attributes: createMessagingAttributes({
+        mode,
+        sourceApplication,
+        targetApplication: applicationId,
+        messageName
+      })
+    },
+    parentContext
+  )
+
+  const spanContext = trace.setSpan(parentContext, span)
+  let result
+
+  try {
+    result = context.with(spanContext, () => handler(data, handlerContext))
+  } catch (error) {
+    endSpan(span, error)
+    throw error
+  }
+
+  if (result?.then) {
+    return result.then(
+      value => {
+        endSpan(span)
+        return value
+      },
+      error => {
+        endSpan(span, error)
+        throw error
+      }
+    )
+  }
+
+  endSpan(span)
+  return result
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/itc",
-  "version": "3.52.4",
+  "version": "3.53.0",
   "description": "",
   "main": "lib/index.js",
   "type": "module",
@@ -25,6 +25,7 @@
   },
   "dependencies": {
     "@fastify/error": "^4.0.0",
+    "@opentelemetry/api": "^1.9.0",
     "@watchable/unpromise": "^1.0.2"
   },
   "engines": {