@platformatic/telemetry 3.4.1 → 3.5.0

package/NOTICE

@@ -11,3 +11,8 @@
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
+
+ The files in `test/otelserver/opentelemetry` has been created by the OpenTelemetry community and are licensed under the Apache License 2.0. The original files can be found at
+ https://github.com/open-telemetry/opentelemetry-proto/tree/1608f92cf08119f9aec237c910b200d1317ec696/opentelemetry 
+
+ 

package/eslint.config.js

@@ -1,3 +1,5 @@
-'use strict'
+import neostandard from 'neostandard'
 
-module.exports = require('neostandard')({})
+export default neostandard({
+  ignores: ['**/.next', '**/dist', '**/tmp', 'test/fixtures/**']
+})

package/index.js

@@ -1,11 +1,3 @@
-'use strict'
-
-const telemetry = require('./lib/telemetry')
-const schema = require('./lib/schema')
-const setupNodeHTTPTelemetry = require('./lib/node-http-telemetry')
-
-module.exports = {
-  telemetry,
-  schema,
-  setupNodeHTTPTelemetry
-}
+export * as schema from './lib/schema.js'
+export * as telemetry from './lib/telemetry.js'
+export { createTelemetryThreadInterceptorHooks } from './lib/thread-interceptor-hooks.js'

package/lib/fastify-text-map.js

@@ -1,22 +1,15 @@
-'use strict'
-
-const fastifyTextMapGetter = {
+export const fastifyTextMapGetter = {
   get (request, key) {
     return request.headers[key]
   },
   /* istanbul ignore next */
   keys (request) {
     return Object.keys(request.headers)
-  },
+  }
 }
 
-const fastifyTextMapSetter = {
+export const fastifyTextMapSetter = {
   set (reply, key, value) {
     reply.headers({ [key]: value })
-  },
-}
-
-module.exports = {
-  fastifyTextMapGetter,
-  fastifyTextMapSetter,
+  }
 }

package/lib/file-span-exporter.js

@@ -0,0 +1,51 @@
+import { ExportResultCode, hrTimeToMicroseconds } from '@opentelemetry/core'
+import { appendFileSync } from 'node:fs'
+import { resolve as resolvePath } from 'node:path'
+import { workerData } from 'node:worker_threads'
+
+// Export spans to a file, mostly for testing purposes.
+export class FileSpanExporter {
+  #path
+  constructor (opts) {
+    this.#path = resolvePath(workerData?.dirname ?? process.cwd(), opts.path ?? 'spans.log')
+  }
+
+  export (spans, resultCallback) {
+    for (const span of spans) {
+      appendFileSync(this.#path, JSON.stringify(this.#exportInfo(span)) + '\n')
+    }
+    resultCallback(ExportResultCode.SUCCESS)
+  }
+
+  shutdown () {
+    return this.forceFlush()
+  }
+
+  forceFlush () {
+    return Promise.resolve()
+  }
+
+  #exportInfo (span) {
+    return {
+      traceId: span.spanContext().traceId,
+      // parentId has been removed from otel 2.0, we need to get it from parentSpanContext
+      parentSpanContext: {
+        traceId: span.parentSpanContext?.traceId,
+        spanId: span.parentSpanContext?.spanId
+      },
+      traceState: span.spanContext().traceState?.serialize(),
+      name: span.name,
+      id: span.spanContext().spanId,
+      kind: span.kind,
+      timestamp: hrTimeToMicroseconds(span.startTime),
+      duration: hrTimeToMicroseconds(span.duration),
+      attributes: span.attributes,
+      status: span.status,
+      events: span.events,
+      links: span.links,
+      resource: span.resource,
+      // instrumentationLibrary is deprecated in otel 2.0, we need to use instrumentationScope
+      instrumentationScope: span.instrumentationLibrary || span.instrumentationScope
+    }
+  }
+}

package/lib/import-or-local.js

@@ -0,0 +1,14 @@
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+export async function importOrLocal ({ projectDir, pkg }) {
+  try {
+    return import(pkg)
+  } catch (err) {
+    const pkgJsonPath = join(projectDir, 'package.json')
+    const _require = createRequire(pkgJsonPath)
+    const fileToImport = _require.resolve(pkg)
+    return import(pathToFileURL(fileToImport))
+  }
+}

package/lib/multispan-processor.js

@@ -1,8 +1,6 @@
-'use strict'
-
 // This implements the SpanProcessor interface:
 // https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-sdk-trace-base/src/SpanProcessor.ts
-class MultiSpanProcessor {
+export class MultiSpanProcessor {
   constructor (_spanProcessors = []) {
     this._spanProcessors = _spanProcessors
   }
@@ -35,5 +33,3 @@ class MultiSpanProcessor {
     return Promise.all(promises)
   }
 }
-
-module.exports = { MultiSpanProcessor }

package/lib/node-telemetry.js

@@ -0,0 +1,142 @@
+import { HttpInstrumentation } from '@opentelemetry/instrumentation-http'
+import { UndiciInstrumentation } from '@opentelemetry/instrumentation-undici'
+import { resourceFromAttributes } from '@opentelemetry/resources'
+import * as opentelemetry from '@opentelemetry/sdk-node'
+import {
+  BatchSpanProcessor,
+  ConsoleSpanExporter,
+  InMemorySpanExporter,
+  SimpleSpanProcessor
+} from '@opentelemetry/sdk-trace-base'
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions'
+import { abstractLogger } from '@platformatic/foundation'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { readFileSync, statSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
+import { resolve } from 'node:path'
+import process from 'node:process'
+import util from 'node:util'
+import { workerData } from 'node:worker_threads'
+import { FileSpanExporter } from './file-span-exporter.js'
+import { getInstrumentations } from './pluggable-instrumentations.js'
+
+const debuglog = util.debuglog('@platformatic/telemetry')
+const require = createRequire(import.meta.url)
+
+// See: https://www.npmjs.com/package/@opentelemetry/instrumentation-http
+// When this is fixed we should set this to 'http' and fixe the tests
+// https://github.com/open-telemetry/opentelemetry-js/issues/5103
+process.env.OTEL_SEMCONV_STABILITY_OPT_IN = 'http/dup'
+
+const setupNodeHTTPTelemetry = async (opts, applicationDir) => {
+  const { applicationName, instrumentations = [] } = opts
+  const additionalInstrumentations = await getInstrumentations(instrumentations, applicationDir)
+
+  let exporter = opts.exporter
+  if (!exporter) {
+    abstractLogger.warn('No exporter configured, defaulting to console.')
+    exporter = { type: 'console' }
+  }
+  const exporters = Array.isArray(exporter) ? exporter : [exporter]
+  const spanProcessors = []
+  for (const exporter of exporters) {
+    // Exporter config:
+    // https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_exporter_zipkin.ExporterConfig.html
+    const exporterOptions = { ...exporter.options, applicationName }
+
+    let exporterObj
+    if (exporter.type === 'console') {
+      exporterObj = new ConsoleSpanExporter(exporterOptions)
+    } else if (exporter.type === 'otlp') {
+      const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto')
+      exporterObj = new OTLPTraceExporter(exporterOptions)
+    } else if (exporter.type === 'zipkin') {
+      const { ZipkinExporter } = require('@opentelemetry/exporter-zipkin')
+      exporterObj = new ZipkinExporter(exporterOptions)
+    } else if (exporter.type === 'memory') {
+      exporterObj = new InMemorySpanExporter()
+    } else if (exporter.type === 'file') {
+      exporterObj = new FileSpanExporter(exporterOptions)
+    } else {
+      abstractLogger.warn(`Unknown exporter type: ${exporter.type}, defaulting to console.`)
+      exporterObj = new ConsoleSpanExporter(exporterOptions)
+    }
+
+    let spanProcessor
+    // We use a SimpleSpanProcessor for the console/memory exporters and a BatchSpanProcessor for the others.
+    // , unless "processor" is set to "simple" (used only in tests)
+    if (exporter.processor === 'simple' || ['memory', 'console', 'file'].includes(exporter.type)) {
+      spanProcessor = new SimpleSpanProcessor(exporterObj)
+    } else {
+      spanProcessor = new BatchSpanProcessor(exporterObj)
+    }
+    spanProcessors.push(spanProcessor)
+  }
+
+  const clientSpansAls = new AsyncLocalStorage()
+  globalThis.platformatic = globalThis.platformatic || {}
+  globalThis.platformatic.clientSpansAls = clientSpansAls
+
+  const sdk = new opentelemetry.NodeSDK({
+    spanProcessors, // https://github.com/open-telemetry/opentelemetry-js/issues/4881#issuecomment-2358059714
+    instrumentations: [
+      new UndiciInstrumentation({
+        responseHook: span => {
+          const store = clientSpansAls.getStore()
+          if (store) {
+            store.span = span
+          }
+        }
+      }),
+      new HttpInstrumentation(),
+      ...additionalInstrumentations
+    ],
+    resource: resourceFromAttributes({
+      [ATTR_SERVICE_NAME]: applicationName
+    })
+  })
+  sdk.start()
+
+  process.on('SIGTERM', () => {
+    sdk
+      .shutdown()
+      .then(() => debuglog('Tracing terminated'))
+      .catch(error => debuglog('Error terminating tracing', error))
+  })
+}
+
+async function main () {
+  let data = null
+  const useWorkerData = !!workerData
+
+  if (useWorkerData) {
+    data = workerData
+  } else if (process.env.PLT_MANAGER_ID) {
+    try {
+      const dataPath = resolve(tmpdir(), 'platformatic', 'runtimes', `${process.env.PLT_MANAGER_ID}.json`)
+      statSync(dataPath)
+      const jsonData = JSON.parse(readFileSync(dataPath, 'utf8'))
+      data = jsonData.data
+      debuglog(`Loaded data from ${dataPath}`)
+    } catch (e) {
+      debuglog('Error reading data from file %o', e)
+    }
+  }
+
+  if (data) {
+    debuglog('Setting up telemetry %o', data)
+    const applicationDir = data.applicationConfig?.path
+    const telemetryConfig = useWorkerData ? data?.applicationConfig?.telemetry : data?.telemetryConfig
+    if (telemetryConfig) {
+      debuglog('telemetryConfig %o', telemetryConfig)
+      setupNodeHTTPTelemetry(telemetryConfig, applicationDir)
+    }
+  }
+}
+
+try {
+  main()
+} catch (e) {
+  debuglog('Error in main %o', e)
+}

package/lib/platformatic-context.js

@@ -1,6 +1,4 @@
-'use strict'
-
-const { createContextKey } = require('@opentelemetry/api')
+import { createContextKey } from '@opentelemetry/api'
 
 // Unfortunately, these kesy are not exported by the OpenTelemetry API :()
 // And we HAVE to use these keys because are used by the propagators
@@ -9,13 +7,13 @@ const SPAN_KEY = createContextKey('OpenTelemetry Context Key SPAN')
 // This is basicaklly the same as https://github.com/open-telemetry/opentelemetry-js/blob/main/api/src/context/context.ts#L85
 // (so just a wrapper around a Map)
 // Note that mutating the context is not allowed by the OpenTelemetry spec.
-class PlatformaticContext {
+export class PlatformaticContext {
   _currentContext
 
   constructor (parentContext) {
     this._currentContext = parentContext ? new Map(parentContext) : new Map()
 
-    this.getValue = (key) => this._currentContext.get(key)
+    this.getValue = key => this._currentContext.get(key)
 
     // Must create and return a new context
     this.setValue = (key, value) => {
@@ -26,16 +24,14 @@ class PlatformaticContext {
 
     // Must return a new context
     /* istanbul ignore next */
-    this.deleteValue = (key) => {
+    this.deleteValue = key => {
       const context = new PlatformaticContext(this._currentContext)
       context._currentContext.delete(key)
       return context
     }
 
-    this.setSpan = (span) => {
+    this.setSpan = span => {
       return this.setValue(SPAN_KEY, span)
     }
   }
 }
-
-module.exports = { PlatformaticContext }

package/lib/platformatic-trace-provider.js

@@ -1,11 +1,14 @@
-'use strict'
+import { CompositePropagator, merge, W3CTraceContextPropagator } from '@opentelemetry/core'
+import { emptyResource } from '@opentelemetry/resources'
+import { AlwaysOnSampler } from '@opentelemetry/sdk-trace-base'
+import { createRequire } from 'node:module'
+import { MultiSpanProcessor } from './multispan-processor.js'
 
-const { Resource } = require('@opentelemetry/resources')
-const { AlwaysOnSampler, merge, CompositePropagator, W3CTraceContextPropagator } = require('@opentelemetry/core')
-const { Tracer } = require('@opentelemetry/sdk-trace-base')
-const { MultiSpanProcessor } = require('./multispan-processor')
+const require = createRequire(import.meta.url)
+// We need to import the Tracer to write our own TracerProvider that does NOT extend the OpenTelemetry one.
+const { Tracer } = require('@opentelemetry/sdk-trace-base/build/src/Tracer')
 
-class PlatformaticTracerProvider {
+export class PlatformaticTracerProvider {
   activeSpanProcessor = null
   _registeredSpanProcessors = []
   // This MUST be called `resource`, see: https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-sdk-trace-base/src/Tracer.ts#L57
@@ -16,19 +19,19 @@ class PlatformaticTracerProvider {
     const mergedConfig = merge(
       {},
       {
-        sampler: new AlwaysOnSampler(),
+        sampler: new AlwaysOnSampler()
       },
       config
     )
-    this.resource = mergedConfig.resource ?? Resource.empty()
+    this.resource = mergedConfig.resource ?? emptyResource
     this._config = Object.assign({}, mergedConfig, {
-      resource: this.resource,
+      resource: this.resource
     })
   }
 
   // This is the only mandatory API: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#get-a-tracer
-  getTracer (name, version, options) {
-    return new Tracer({ name, version }, this._config, this)
+  getTracer (name, version) {
+    return new Tracer({ name, version }, this._config, this.resource, this.activeSpanProcessor)
   }
 
   addSpanProcessor (spanProcessor) {
@@ -37,9 +40,7 @@ class PlatformaticTracerProvider {
     } else {
       this._registeredSpanProcessors.push(spanProcessor)
     }
-    this.activeSpanProcessor = new MultiSpanProcessor(
-      this._registeredSpanProcessors
-    )
+    this.activeSpanProcessor = new MultiSpanProcessor(this._registeredSpanProcessors)
   }
 
   getActiveSpanProcessor () {
@@ -49,14 +50,13 @@ class PlatformaticTracerProvider {
   getPropagator () {
     return new CompositePropagator({
       propagators: [
-        new W3CTraceContextPropagator(), // see: https://www.w3.org/TR/trace-context/
-      ],
+        new W3CTraceContextPropagator() // see: https://www.w3.org/TR/trace-context/
+      ]
     })
   }
 
   forceFlush () {
     // Let's do a fire-and-forget of forceFlush on all the processor for the time being.
-    // TODO: manage errors
     this._registeredSpanProcessors.forEach(spanProcessor => spanProcessor.forceFlush())
   }
 
@@ -64,5 +64,3 @@ class PlatformaticTracerProvider {
     return this.activeSpanProcessor.shutdown()
   }
 }
-
-module.exports = { PlatformaticTracerProvider }

package/lib/pluggable-instrumentations.js

@@ -0,0 +1,62 @@
+import { importOrLocal } from './import-or-local.js'
+
+// These are already set automatically by the runtime, so we throw
+// if set again.
+const defaultInstrumentations = ['@opentelemetry/instrumentation-http', '@opentelemetry/instrumentation-undici']
+
+async function getInstrumentationInstance (instrumentationConfig, applicationDir) {
+  if (typeof instrumentationConfig === 'string') {
+    instrumentationConfig = { package: instrumentationConfig, exportName: 'default', options: {} }
+  }
+  const { package: packageName, exportName = 'default', options = {} } = instrumentationConfig
+
+  if (defaultInstrumentations.includes(packageName)) {
+    throw new Error(
+      `Instrumentation package ${packageName} is already included by default, please remove it from your config.`
+    )
+  }
+
+  let mod
+  try {
+    mod = await importOrLocal({ pkg: packageName, projectDir: applicationDir })
+  } catch (err) {
+    throw new Error(
+      `Instrumentation package not found: ${instrumentationConfig.package}, please add it to your dependencies.`
+    )
+  }
+
+  let Instrumenter = mod[exportName]
+  if (!Instrumenter || typeof Instrumenter !== 'function') {
+    // Check for for an export that ends with 'Instrumentation'. We need to do that because unfortunately
+    // each instrumenttions has different named export. But all of them ends with 'Instrumentation'.
+    const possibleExports = Object.keys(mod).filter(key => key.endsWith('Instrumentation'))
+    if (possibleExports.length === 0) {
+      throw new Error(`Instrumentation export not found: ${exportName} in ${packageName}. Please specify in config`)
+    }
+    if (possibleExports.length > 1) {
+      throw new Error(
+        `Multiple Instrumentation exports found: ${possibleExports} in ${packageName}. Please specify in config`
+      )
+    }
+    Instrumenter = mod[possibleExports[0]]
+  }
+  const instance = new Instrumenter(options)
+  return instance
+}
+
+// Example of instrumentations config:
+// "instrumentations": [
+//       "@opentelemetry/instrumentation-express",
+//       {
+//          "package": "@opentelemetry/instrumentation-redisjs",
+//          "exportName": "RedisInstrumentation",
+//          "options": { "foo": "bar" }
+//       }
+export async function getInstrumentations (configs = [], applicationDir) {
+  const instrumentations = []
+  for (const instrumentationConfig of configs) {
+    const instance = await getInstrumentationInstance(instrumentationConfig, applicationDir)
+    instrumentations.push(instance)
+  }
+  return instrumentations
+}

package/lib/schema.js

@@ -1,73 +1,3 @@
-'use strict'
+import { schemaComponents } from '@platformatic/foundation'
 
-const ExporterSchema = {
-  type: 'object',
-  properties: {
-    type: {
-      type: 'string',
-      enum: ['console', 'otlp', 'zipkin', 'memory'],
-      default: 'console',
-    },
-    options: {
-      type: 'object',
-      description: 'Options for the exporter. These are passed directly to the exporter.',
-      properties: {
-        url: {
-          type: 'string',
-          description: 'The URL to send the traces to. Not used for console or memory exporters.',
-        },
-        headers: {
-          type: 'object',
-          description: 'Headers to send to the exporter. Not used for console or memory exporters.',
-        },
-      },
-    },
-    additionalProperties: false,
-  },
-}
-
-const TelemetrySchema = {
-  $id: '/OpenTelemetry',
-  type: 'object',
-  properties: {
-    serviceName: {
-      type: 'string',
-      description: 'The name of the service. Defaults to the folder name if not specified.',
-    },
-    version: {
-      type: 'string',
-      description: 'The version of the service (optional)',
-    },
-    skip: {
-      type: 'array',
-      description: 'An array of paths to skip when creating spans. Useful for health checks and other endpoints that do not need to be traced.',
-      items: {
-        type: 'object',
-        properties: {
-          path: {
-            type: 'string',
-            description: 'The path to skip. Can be a string or a regex.',
-          },
-          method: {
-            description: 'HTTP method to skip',
-            type: 'string',
-            enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'],
-          },
-        },
-      },
-    },
-    exporter: {
-      anyOf: [
-        {
-          type: 'array',
-          items: ExporterSchema,
-        },
-        ExporterSchema,
-      ],
-    },
-  },
-  required: ['serviceName'],
-  additionalProperties: false,
-}
-
-module.exports = TelemetrySchema
+export default schemaComponents.telemetry