@platformatic/telemetry 0.34.0 → 0.35.0

package/lib/schema.js

@@ -12,6 +12,13 @@ const TelemetrySchema = {
       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: 'string'
+      }
+    },
     exporter: {
       type: 'object',
       properties: {

package/lib/telemetry.js

@@ -1,13 +1,14 @@
 'use strict'
 
 const fp = require('fastify-plugin')
-const { SpanStatusCode } = require('@opentelemetry/api')
+const { SpanStatusCode, SpanKind } = require('@opentelemetry/api')
 const { ConsoleSpanExporter, BatchSpanProcessor, SimpleSpanProcessor, InMemorySpanExporter } = require('@opentelemetry/sdk-trace-base')
 const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions')
 const { Resource } = require('@opentelemetry/resources')
 const { PlatformaticTracerProvider } = require('./platformatic-trace-provider')
 const { PlatformaticContext } = require('./platformatic-context')
 const { fastifyTextMapGetter, fastifyTextMapSetter } = require('./fastify-text-map')
+const fastUri = require('fast-uri')
 
 // Platformatic telemetry plugin.
 // Supported Exporters:
@@ -32,16 +33,22 @@ function formatSpanName (request) {
   return routerPath ? `${method} ${routerPath}` : method
 }
 
-const defaultFormatSpanAttributes = {
+const formatSpanAttributes = {
   request (request) {
+    const { hostname, method, url, protocol } = request
+    // Inspired by: https://github.com/fastify/fastify-url-data/blob/master/plugin.js#L11
+    const urlData = fastUri.parse(`${protocol}://${hostname}${url}`)
     return {
-      'req.method': request.raw.method,
-      'req.url': request.raw.url
+      'server.address': hostname,
+      'server.port': urlData.port,
+      'http.request.method': method,
+      'url.path': urlData.path,
+      'url.scheme': protocol
     }
   },
   reply (reply) {
     return {
-      'reply.statusCode': reply.statusCode
+      'http.response.status_code': reply.statusCode
     }
   },
   error (error) {
@@ -60,7 +67,7 @@ const setupProvider = (app, opts) => {
     app.log.warn('No exporter configured, defaulting to console.')
     exporter = { type: 'console' }
   }
-  app.log.info(`Setting up telemetry for service: ${serviceName} version: ${version} and exporter of type ${exporter.type}`)
+  app.log.info(`Setting up telemetry for service: ${serviceName}${version ? ' version: ' + version : ''} with exporter of type ${exporter.type}`)
   const provider = new PlatformaticTracerProvider({
     resource: new Resource({
       [SemanticResourceAttributes.SERVICE_NAME]: serviceName,
@@ -101,16 +108,17 @@ async function setupTelemetry (app, opts) {
   // const { serviceName, version } = opts
   const openTelemetryAPIs = setupProvider(app, opts)
   const { tracer, propagator, provider } = openTelemetryAPIs
-
-  const formatSpanAttributes = {
-    ...defaultFormatSpanAttributes,
-    ...(opts.formatSpanAttributes || {})
-  }
+  const skipOperations = opts.skip || []
 
   // expose the span as a request decorator
   app.decorateRequest('span')
 
   const startSpan = async (request) => {
+    if (skipOperations.includes(`${request.method}${request.url}`)) {
+      request.log.debug({ operation: `${request.method}${request.url}` }, 'Skipping telemetry')
+      return
+    }
+
     // We populate the context with the incoming request headers
     let context = propagator.extract(new PlatformaticContext(), request, fastifyTextMapGetter)
 
@@ -119,6 +127,7 @@ async function setupTelemetry (app, opts) {
       {},
       context
     )
+    span.kind = SpanKind.SERVER
     // Next 2 lines are needed by W3CTraceContextPropagator
     context = context.setSpan(span)
     span.setAttributes(formatSpanAttributes.request(request))
@@ -132,19 +141,23 @@ async function setupTelemetry (app, opts) {
   }
 
   const injectPropagationHeadersInReply = async (request, reply) => {
-    const context = request.span.context
-    propagator.inject(context, reply, fastifyTextMapSetter)
+    if (request.span) {
+      const context = request.span.context
+      propagator.inject(context, reply, fastifyTextMapSetter)
+    }
   }
 
   const endSpan = async (request, reply) => {
     const span = request.span
-    const spanStatus = { code: SpanStatusCode.OK }
-    if (reply.statusCode >= 400) {
-      spanStatus.code = SpanStatusCode.ERROR
+    if (span) {
+      const spanStatus = { code: SpanStatusCode.OK }
+      if (reply.statusCode >= 400) {
+        spanStatus.code = SpanStatusCode.ERROR
+      }
+      span.setAttributes(formatSpanAttributes.reply(reply))
+      span.setStatus(spanStatus)
+      span.end()
     }
-    span.setAttributes(formatSpanAttributes.reply(reply))
-    span.setStatus(spanStatus)
-    span.end()
   }
 
   app.addHook('onRequest', startSpan)
@@ -174,11 +187,30 @@ async function setupTelemetry (app, opts) {
   // - closing the span
   const startSpanClient = (url, method, ctx) => {
     let context = ctx || new PlatformaticContext()
+    const urlObj = fastUri.parse(url)
+
+    if (skipOperations.includes(`${method}${urlObj.path}`)) {
+      app.log.debug({ operation: `${method}${urlObj.path}` }, 'Skipping telemetry')
+      return
+    }
+
     /* istanbul ignore next */
     method = method || ''
-    const span = tracer.startSpan(`${method} ${url}`, {}, context)
+    const name = `${method} ${urlObj.scheme}://${urlObj.host}:${urlObj.port}${urlObj.path}`
+
+    const span = tracer.startSpan(name, {}, context)
+    span.kind = SpanKind.CLIENT
+
     /* istanbul ignore next */
-    const attributes = url ? { 'server.url': url } : {}
+    const attributes = url
+      ? {
+          'server.address': urlObj.host,
+          'server.port': urlObj.port,
+          'http.request.method': method,
+          'url.full': url,
+          'url.path': urlObj.path
+        }
+      : {}
     span.setAttributes(attributes)
 
     // Next 2 lines are needed by W3CTraceContextPropagator
@@ -200,7 +232,7 @@ async function setupTelemetry (app, opts) {
         spanStatus.code = SpanStatusCode.ERROR
       }
       span.setAttributes({
-        'response.statusCode': response.statusCode
+        'http.response.status_code': response.statusCode
       })
       span.setStatus(spanStatus)
     } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/telemetry",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "OpenTelemetry integration for Platformatic",
   "main": "index.js",
   "author": "Marco Piraccini <marco.piraccini@gmail.com>",
@@ -23,6 +23,7 @@
     "@opentelemetry/resources": "^1.15.0",
     "@opentelemetry/sdk-trace-base": "^1.15.0",
     "@opentelemetry/semantic-conventions": "^1.15.0",
+    "fast-uri": "^2.2.0",
     "fastify-plugin": "^4.5.0"
   },
   "scripts": {

package/test/client.test.js

@@ -2,7 +2,7 @@
 
 const { test } = require('tap')
 const fastify = require('fastify')
-const { SpanStatusCode } = require('@opentelemetry/api')
+const { SpanStatusCode, SpanKind } = require('@opentelemetry/api')
 const telemetryPlugin = require('../lib/telemetry')
 const { PlatformaticContext } = require('../lib/platformatic-context')
 const { fastifyTextMapGetter } = require('../lib/fastify-text-map')
@@ -29,7 +29,6 @@ test('should add the propagation headers correctly, new propagation started', as
 
   const app = await setupApp({
     serviceName: 'test-service',
-    version: '1.0.0',
     exporter: {
       type: 'memory'
     }
@@ -126,16 +125,21 @@ test('should trace a client request', async ({ equal, same, teardown }) => {
   // We have two one for the client and one for the server
   const spanServer = finishedSpans[0]
   equal(spanServer.name, 'GET /test')
+  equal(spanServer.kind, SpanKind.SERVER)
   equal(spanServer.status.code, SpanStatusCode.OK)
-  equal(spanServer.attributes['req.method'], 'GET')
-  equal(spanServer.attributes['req.url'], '/test')
-  equal(spanServer.attributes['reply.statusCode'], 200)
+  equal(spanServer.attributes['http.request.method'], 'GET')
+  equal(spanServer.attributes['url.path'], '/test')
+  equal(spanServer.attributes['http.response.status_code'], 200)
 
   const spanClient = finishedSpans[1]
   equal(spanClient.name, 'GET http://localhost:3000/test')
+  equal(spanClient.kind, SpanKind.CLIENT)
   equal(spanClient.status.code, SpanStatusCode.OK)
-  equal(spanClient.attributes['server.url'], 'http://localhost:3000/test')
-  equal(spanClient.attributes['response.statusCode'], 200)
+  equal(spanClient.attributes['url.full'], 'http://localhost:3000/test')
+  equal(spanClient.attributes['http.response.status_code'], 200)
+  equal(spanClient.attributes['server.port'], 3000)
+  equal(spanClient.attributes['server.address'], 'localhost')
+  equal(spanClient.attributes['url.path'], '/test')
 
   // The traceparent header is added to the request and propagated to the server
   equal(receivedHeaders.traceparent, telemetryHeaders.traceparent)
@@ -175,16 +179,18 @@ test('should trace a client request failing', async ({ equal, same, teardown })
   // We have two one for the client and one for the server
   const spanServer = finishedSpans[0]
   equal(spanServer.name, 'GET')
+  equal(spanServer.kind, SpanKind.SERVER)
   equal(spanServer.status.code, SpanStatusCode.ERROR)
-  equal(spanServer.attributes['req.method'], 'GET')
-  equal(spanServer.attributes['req.url'], '/wrong')
-  equal(spanServer.attributes['reply.statusCode'], 404)
+  equal(spanServer.attributes['http.request.method'], 'GET')
+  equal(spanServer.attributes['url.path'], '/wrong')
+  equal(spanServer.attributes['http.response.status_code'], 404)
 
   const spanClient = finishedSpans[1]
   equal(spanClient.name, 'GET http://localhost:3000/test')
+  equal(spanClient.kind, SpanKind.CLIENT)
   equal(spanClient.status.code, SpanStatusCode.ERROR)
-  equal(spanClient.attributes['server.url'], 'http://localhost:3000/test')
-  equal(spanClient.attributes['response.statusCode'], 404)
+  equal(spanClient.attributes['url.full'], 'http://localhost:3000/test')
+  equal(spanClient.attributes['http.response.status_code'], 404)
 })
 
 test('should trace a client request failing (no HTTP error)', async ({ equal, same, teardown }) => {
@@ -219,8 +225,48 @@ test('should trace a client request failing (no HTTP error)', async ({ equal, sa
   const spanClient = finishedSpans[0]
   equal(spanClient.name, 'GET http://localhost:3000/test')
   equal(spanClient.status.code, SpanStatusCode.ERROR)
-  equal(spanClient.attributes['server.url'], 'http://localhost:3000/test')
+  equal(spanClient.attributes['url.full'], 'http://localhost:3000/test')
   equal(spanClient.attributes['error.name'], 'Error')
   equal(spanClient.attributes['error.message'], 'KABOOM!!!')
   equal(spanClient.attributes['error.stack'].includes('Error: KABOOM!!!'), true)
 })
+
+test('should not add the query in span name', async ({ equal, same, teardown }) => {
+  const handler = async (request, reply) => {
+    return { foo: 'bar' }
+  }
+
+  const app = await setupApp({
+    serviceName: 'test-service',
+    exporter: {
+      type: 'memory'
+    }
+  }, handler, teardown)
+
+  const { startSpanClient } = app.openTelemetry
+
+  const url = 'http://localhost:3000/test?foo=bar'
+  const { span } = startSpanClient(url, 'GET')
+  same(span.name, 'GET http://localhost:3000/test')
+})
+
+test('should ignore the skipped operations', async ({ equal, same, ok, teardown }) => {
+  const handler = async (request, reply) => {
+    return { foo: 'bar' }
+  }
+
+  const app = await setupApp({
+    serviceName: 'test-service',
+    skip: ['POST/skipme'],
+    exporter: {
+      type: 'memory'
+    }
+  }, handler, teardown)
+
+  const { startSpanClient } = app.openTelemetry
+
+  const url = 'http://localhost:3000/skipme'
+  const ret = startSpanClient(url, 'POST')
+  // no spam should be created
+  ok(!ret)
+})

package/test/telemetry.test.js

@@ -2,7 +2,7 @@
 
 const { test } = require('tap')
 const fastify = require('fastify')
-const { SpanStatusCode } = require('@opentelemetry/api')
+const { SpanStatusCode, SpanKind } = require('@opentelemetry/api')
 const telemetryPlugin = require('../lib/telemetry')
 
 async function setupApp (pluginOpts, routeHandler, teardown) {
@@ -46,11 +46,53 @@ test('should trace a request not failing', async ({ equal, same, teardown }) =>
   const finishedSpans = exporter.getFinishedSpans()
   equal(finishedSpans.length, 1)
   const span = finishedSpans[0]
+  equal(span.kind, SpanKind.SERVER)
   equal(span.name, 'GET /test')
   equal(span.status.code, SpanStatusCode.OK)
-  equal(span.attributes['req.method'], 'GET')
-  equal(span.attributes['req.url'], '/test')
-  equal(span.attributes['reply.statusCode'], 200)
+  equal(span.attributes['http.request.method'], 'GET')
+  equal(span.attributes['url.path'], '/test')
+  equal(span.attributes['http.response.status_code'], 200)
+  equal(span.attributes['url.scheme'], 'http')
+  equal(span.attributes['server.address'], 'test')
+  const resource = span.resource
+  same(resource.attributes['service.name'], 'test-service')
+  same(resource.attributes['service.version'], '1.0.0')
+})
+
+test('should not put query in `url.path', async ({ equal, same, teardown }) => {
+  const handler = async (request, reply) => {
+    return { foo: 'bar' }
+  }
+
+  const injectArgs = {
+    method: 'GET',
+    url: '/test?foo=bar',
+    headers: {
+      host: 'test'
+    }
+  }
+
+  const app = await setupApp({
+    serviceName: 'test-service',
+    version: '1.0.0',
+    exporter: {
+      type: 'memory'
+    }
+  }, handler, teardown)
+
+  await app.inject(injectArgs)
+  const { exporter } = app.openTelemetry
+  const finishedSpans = exporter.getFinishedSpans()
+  equal(finishedSpans.length, 1)
+  const span = finishedSpans[0]
+  equal(span.kind, SpanKind.SERVER)
+  equal(span.name, 'GET /test')
+  equal(span.status.code, SpanStatusCode.OK)
+  equal(span.attributes['http.request.method'], 'GET')
+  equal(span.attributes['url.path'], '/test')
+  equal(span.attributes['http.response.status_code'], 200)
+  equal(span.attributes['url.scheme'], 'http')
+  equal(span.attributes['server.address'], 'test')
   const resource = span.resource
   same(resource.attributes['service.name'], 'test-service')
   same(resource.attributes['service.version'], '1.0.0')
@@ -77,9 +119,9 @@ test('request should add attribute to a span', async ({ equal, same, teardown })
   const span = finishedSpans[0]
   equal(span.name, 'GET /test')
   equal(span.status.code, SpanStatusCode.OK)
-  equal(span.attributes['req.method'], 'GET')
-  equal(span.attributes['req.url'], '/test')
-  equal(span.attributes['reply.statusCode'], 200)
+  equal(span.attributes['http.request.method'], 'GET')
+  equal(span.attributes['url.path'], '/test')
+  equal(span.attributes['http.response.status_code'], 200)
   // This is the attribute we added
   equal(span.attributes.foo, 'bar')
   const resource = span.resource
@@ -127,9 +169,9 @@ test('should trace a request that fails', async ({ equal, same, teardown }) => {
   const span = finishedSpans[0]
   equal(span.name, 'GET /test')
   equal(span.status.code, SpanStatusCode.ERROR)
-  equal(span.attributes['req.method'], 'GET')
-  equal(span.attributes['req.url'], '/test')
-  equal(span.attributes['reply.statusCode'], 500)
+  equal(span.attributes['http.request.method'], 'GET')
+  equal(span.attributes['url.path'], '/test')
+  equal(span.attributes['http.response.status_code'], 500)
   equal(span.attributes['error.message'], 'booooom!!!')
   const resource = span.resource
   same(resource.attributes['service.name'], 'test-service')
@@ -206,3 +248,33 @@ test('wrong exporter is configured, should default to console', async ({ equal,
   const { exporter } = app.openTelemetry
   same(exporter.constructor.name, 'ConsoleSpanExporter')
 })
+
+test('should not trace if the operation is skipped', async ({ equal, same, teardown }) => {
+  const handler = async (request, reply) => {
+    return { foo: 'bar' }
+  }
+
+  const app = await setupApp({
+    serviceName: 'test-service',
+    version: '1.0.0',
+    skip: [
+      'GET/documentation/json'
+    ],
+    exporter: {
+      type: 'memory'
+    }
+  }, handler, teardown)
+
+  const injectArgs = {
+    method: 'GET',
+    url: '/documentation/json',
+    headers: {
+      host: 'test'
+    }
+  }
+
+  await app.inject(injectArgs)
+  const { exporter } = app.openTelemetry
+  const finishedSpans = exporter.getFinishedSpans()
+  equal(finishedSpans.length, 0)
+})